listings

Invocation#

echo-cli listings list --product <id>
echo-cli listings record --product <id> --venue <text> --url <https-url> --field "<fact name>=<text>"... --by <name>
echo-cli listings update --id <listing-id> --field "<fact name>=<text>"... --by <name>
echo-cli listings check --id <listing-id>
echo-cli listings read --id <listing-id> --language <code> [--property "<fact name>=P<number>"]... --by <name>
echo-cli listings page --id <listing-id> [--part "<fact name>=title|description|og_title|og_description|canonical|heading:<n>"]... --by <name>

Inputs and output#

list writes the product's listings by venue: id, product_id, venue, url, fields (what the listing says, by name), properties (the Wikidata property, or for a page read the part of the page, of each fact, once read), recorded_by and recorded_at; record and update write the listing. check writes listing_id, venue, url, fact_sheet_id, differs (each field, listed, fact and source), missing (each fact and value the listing does not show) and unchecked (fields no fact covers). read and page write listing, as read now, and absent, the facts the entity or the page states nothing for.

State effect#

Every verb calls Echo Web's authenticated /api/analytics/listings with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the Listings section of the tracking screen and of Echo Desktop's GEO screen call the same operations, and echo-mcp lists listings (echo_list_listings) and checks them (echo_check_listing). A listing page is recorded once per product; update replaces everything the listing says with the fields given, as read now. check compares each field with the fact of the same name, without regard to case, on the product's fact sheet in force (see geo facts) and changes nothing. read takes a listing at a Wikidata entity page (https://www.wikidata.org/wiki/Q<number>), reads https://www.wikidata.org/wiki/Special:EntityData/<Q id>.json with ECHO_WIKIDATA_USER_AGENT as its User-Agent (https://meta.wikimedia.org/wiki/User-Agent_policy) and replaces what the listing says with each mapped property's values as text: the preferred statements when any, else every one not deprecated, joined by ", "; a quantity as its amount, a time as Wikidata writes it, an item by its label in --language. The --property mapping is kept with the listing; a later read without one uses it.

Refusals#

• A wrong invocation is refused before anything is sent: "listings takes <every verb's usage, separated by semicolons>; got <word>", "listings <verb> does not take <flag>; it takes …", "<flag> needs a value", "listings <verb> needs <flag>" for each flag the verb needs, "--field takes \"<fact name>=<text>\", such as \"description=Scheduling for teams\"; got <text>" and "listings <verb> needs at least one --field \"<fact name>=<text>\"".
• Echo Web answers a bad request with "product_id is required: …", "venue is required: …", "url must be an absolute https address; got <value>", "fields is required: what the listing says, as { \"<fact name>\": \"<text it shows>\" }", "fields.<name> is required: the text the listing shows" or "recorded_by is required: an internal caller has no signed-in user, so it names who is acting"; not found with "no product has id <id>; echo-cli products lists the ones that exist", "no listing has id <id>; echo-cli listings list --product <id> lists them" or "product <id> has published no fact sheet; publish one with echo-cli geo facts publish"; and a conflict with "<url> is already recorded as listing <id>; echo-cli listings update changes what it says". The command prints Echo Web's sentence and exits non-zero.
• read is refused before anything is sent with "--property takes \"<fact name>=<text>\", such as \"website=P856\"; got <text>"; Echo Web refuses it as a bad request with "language is required: the language code an item value is shown in, such as en", "listing <id> is at <url>, not a Wikidata entity page such as https://www.wikidata.org/wiki/Q42; only Wikidata listings are read", "properties is required on the first read: which Wikidata property each fact is, as { \"<fact name>\": \"P<number>\" }" or "properties.<fact> must be a Wikidata property id such as P856; got <value>"; as not found with "Wikidata entity <Q id> states none of <properties>"; and fails naming the cause with "ECHO_WIKIDATA_USER_AGENT is not set: …", "Wikidata answered <address> with HTTP <status>: <body>" or "Wikidata item <Q id> has no label in <language>; read the listing in a language its values are labelled in".
• page calls /api/analytics/listings/page (the Listings section of the tracking screen and of Echo Desktop's GEO screen read the same) and writes { listing, absent }: the listing's page is rendered through Weles now and each fact named by --part (kept with the listing, so a later page needs none) becomes a field holding what that part says — the page's title, its meta description, its Open Graph title or description, its canonical address, or its n-th heading counted from 1 — and absent lists the facts whose part the page leaves empty; the fields replace what the listing said, so check then compares the live page with the fact sheet. It is refused before anything is sent with "--part takes \"<fact name>=<text>\", such as \"description=description\"; got <text>"; Echo Web refuses it as a bad request with "parts is required on the first read: which part of the page each fact is, …", "parts.<fact> must be one of title, description, og_title, og_description, canonical or heading:<n> counted from 1; got <value>" or "listing <id> is a Wikidata entity; echo-cli listings read --id <id> reads it from the entity's data"; as not found with "no listing has id <id>; …" or "<url> says nothing in <parts>"; and fails with Weles's answer when the page cannot be rendered.