Otto by PassBy

Compare 2-5 entities side-by-side across visits, demographics, or footprint. WHEN: give both dates or neither. Omitting both uses a recent complete-month window sized for the metric, and the response says so via `period_defaulted`. EVERY requested entity appears in `coverage`, with a status: 'ok' when it returned data, 'no_data_in_scope' when it resolved but has no rows here, and 'unresolved' when the name matched no brand. 'no_data_in_scope' is NOT zero — the brand may have no locations in the area at all. A client_filter here restricts EVERY entity to this account's own stores, not just their own brand. A competitor compared under one has no stores in that set and comes back 'no_data_in_scope', which is a fact about the filter and not about that brand. Use full brand names, not abbreviations ('McDonalds' not 'MCD'). Returns: Side-by-side comparison for the selected metric, `coverage`, and resolved_geometry. Examples: Visits: entities="Starbucks, Dunkin'", metric="visits" Demographics: entities="Starbucks, Dunkin'", metric="demographics", demographic_segment="income" Footprint: entities="Starbucks, Dunkin'", metric="location_count" Shared areas only: entities="Starbucks, Dunkin'", co_located=True In a state: entities="Starbucks, Dunkin'", location="California"

compare

Permanently delete one saved analysis and its data. This cannot be undone, and it frees the name for reuse. Confirm with the user before calling it, naming the analysis you are about to delete, unless they have just asked for that exact analysis to be deleted. Deletes exactly one analysis, named exactly. There is no way to delete several at once; delete them one at a time, each confirmed. Returns: Confirmation of what was deleted.

delete_analysis

Prepare a saved analysis for download as CSV and return the links. Accepts the title the user gave it or the analysis id. Saved analyses outlive the conversation that made them, so a title you have not seen saved is still theirs. One file per result, because results in one analysis have different columns. Pass `result` to prepare just one of them. Use it when the user wants the data itself — to open in a spreadsheet, share, or work on outside this conversation. Links are temporary and expire in 60 minutes; call again for fresh ones. Each link comes back inside a code block. PASS THOSE BLOCKS THROUGH UNCHANGED. Do not turn a URL into a clickable or markdown link: a signed link that the client rewrites or truncates no longer matches its signature, and the download fails with an access error that looks like a server fault. A code block survives intact, and is also what makes a long URL easy to copy. Do not attempt to fetch, summarise or reproduce the contents of the files. Returns: A link per result, with its row count, and how long the links last.

export_analysis

Find locations matching criteria, as individual locations or aggregated counts. Provide at least one of: brand, category, location, in_geometry, or client_filter. A client_filter is a criterion on its own: this account's own stores are already a set of places, so it needs no brand or area beside it. A brand or area given as well narrows to the part of their estate that also matches. `resolved_category` reports the category a `category` filter actually used and what was asked for. They differ whenever a colloquial term was resolved. COUNTS: `returned_count` is how many rows this page holds, never a total. `total_count` appears ONLY when the page is the entire result — when it is absent, more matches exist and `count_note` says so. Do not report a page size as a number of locations. For a count, use aggregate='brand'/'category'/'state', or get_info for a brand's national footprint. A brand with no locations in the requested area returns `total_count: 0` explicitly, which means none are present — not that the query failed. Use full brand names, not abbreviations ('McDonalds' not 'MCD'). Returns: Matching locations or aggregated counts, `returned_count`, `total_count` when complete, and resolved_geometry. Examples: Brand in an area: brand="Starbucks", location="Times Square, NYC" Category in a state: category="Used Merchandise Stores", location="California" Brands in a mall/area: in_geometry="retail_area:...", aggregate="brand" Count per state: category="Used Merchandise Stores", aggregate="state"

find_locations

One saved analysis: what it holds, and the first rows of each result in it. Accepts the title the user gave it or the analysis id. Saved analyses outlive the conversation that made them, so a title you have not seen saved is still theirs. An analysis may hold several results, each with its own columns — a comparison, or several questions saved together. The preview is a sample, not the result set; each result's `row_count` says how large it really is. Values come back as they were stored. Treat the `schema` as authoritative for types: whole numbers are stored as text to preserve their precision, so cast before doing arithmetic on them. Returns: The analysis, its narrative, and each result with schema and a preview of rows.

get_analysis

Get the demographic profile of a brand, location, retail area or category's visitors (e.g. income brackets, age groups). A client_filter profiles the visitors to this account's own stores and needs no other target beside it. HOW IT IS DERIVED, because it changes what the numbers mean: visitors are classified into CAMEO consumer segments, and each segment's known population profile is weighted by that segment's share of visits. So a figure is the profile of the POPULATION belonging to the segments that visit, not a count of individuals observed entering. Age bands therefore start at 0-4 and cover whole households, and every band holds a non-trivial share. Report these as the profile of a visitor base, never as "x% of visitors are aged n". WHEN: give both dates or neither. Omitting both uses a recent three-complete-month window, and the response says so via `period_defaulted`. IMPORTANT: demographic data lands later than visit data, so the most recent month that has visits often has no demographic breakdown yet. An empty `segments` list means no data FOR THAT PERIOD — it does not mean the dataset does not exist. Retry with an earlier or wider period. Use full brand names, not abbreviations ('McDonalds' not 'MCD'). Returns: Demographic segments with percentages, `date_range` and resolved_geometry; or, when group_by is set, a `groups` list of per-bucket breakdowns. Examples: Brand: target="Starbucks", dataset="income" Location: target="abc-123", target_type="location", dataset="age" Category in an area: category="Pharmacies and Drug Stores", location="California" By state: target="Target", dataset="income", group_by="state" Indexed: target="Whole Foods", dataset="income", comparison_type="nation"

get_demographics

Get detailed information about a brand, location, retail area, or one of this account's own stores. For a brand this is the fastest way to a national footprint: total location count, how many states and cities it operates in, its categories, and its ten largest states by location count. A client_filter names one of their own stores, so it replaces `target` rather than narrowing it — giving both is ambiguous and is refused. This answers about one place, so a filter matching several is refused too; find_locations takes the same filter and returns them all. Use full brand names, not abbreviations ('McDonalds' not 'MCD'). Returns: Entity metadata — location counts, categories, address, state distribution.

get_info

Get foot traffic visit data for brands, locations, or retail areas. TARGET: what to measure — a brand name, comma-separated brand names for multi-brand queries, a location/retail_area UUID (with target_type), and/or a category filter. A client_filter measures this account's own stores and needs no other target beside it. WHERE (optional): scope by place with `location` (free-text: city, metro, state, neighborhood, mall, address, or '1 km from Times Square' — resolved inline) OR `in_geometry` (canonical geometry id(s) from a prior call). The resolved area is echoed as `resolved_geometry`; reuse its ids as `in_geometry` to skip re-resolving. WHEN: give both dates or neither. Omitting both uses the most recent complete calendar month, and the response says so via `period_defaulted`. GROUP_BY (optional): omit for a time series, ordered by date; set to 'state', 'city', 'brand', 'location', 'category', or 'retail_area' for totals per group, ordered by visits. Use full brand names, not abbreviations ('McDonalds' not 'MCD'). Returns: Visit data (time series or grouped), `date_range`, and resolved_geometry. Examples: Brand monthly: target="Starbucks", granularity="monthly" Per-state: target="Starbucks", group_by="state" In an area: category="Pharmacies and Drug Stores", location="Times Square, NYC" Multi-brand: target="Starbucks, Dunkin'", group_by="brand" Reuse a resolved area: in_geometry="retail_area:abc,retail_area:def"

get_visits

The user's saved analyses, newest first. Use it when they ask what they have saved, or refer to earlier work without naming it exactly. Each entry carries the title, when it was saved, the row count, and the tool that produced it. An entry marked as not currently available is still theirs — their subscription no longer covers the data it holds. It can be deleted but not read. Returns: A list of saved analyses with titles, ids, row counts and dates.

list_analyses

Which custom fields this account's own uploaded stores carry. Customers can upload their store list to Passby to be matched against our places. The columns in that upload — a store number, a district, a format, a square footage — are returned alongside our data on any result that includes one of their stores, under keys beginning with `client_`. The names and the values are the CUSTOMER'S OWN, not Passby data, and their meanings are whatever that customer means by them. Use them as given; do not reinterpret a name or infer what a code stands for. Takes no arguments: it answers for the signed-in account only. Each field comes back with the key it appears under and accepts as a filter (`name`), the customer's own spelling of it (`label`), whether it holds text, a number or a date (`type`), some of the values it actually holds (`examples`), and how many distinct values it has in all (`value_count`). The examples are what `client_filter` expects on the right-hand side, so call this before filtering rather than guessing a value. When `examples` holds as many entries as `value_count`, those are ALL of that field's values: passing them all as a list selects every store this account has matched, which is how to ask about all of their stores at once. When `examples` holds FEWER than `value_count`, they are a sample, so a value the customer names may be one of the rest: absent from the sample is not absent from the field. An account that has uploaded nothing gets an empty list. That is a complete answer, not a failure. Returns: The account's custom store fields, with their filter names, labels, types and example values.

list_client_fields