compare
ChatGPTCompare 2-5 entities side-by-side across visits, demographics, or footprint. Use full brand names, not abbreviations ('McDonalds' not 'MCD'). Args: entities: Comma-separated entity names (e.g. 'Starbucks, Dunkin, Peet's') entity_type: 'brand' (only supported type currently) metric: 'visits', 'demographics', or 'location_count' start_date: Start date (YYYY-MM-DD or natural language) end_date: End date (YYYY-MM-DD or natural language) granularity: Visits granularity: 'daily', 'weekly', 'monthly', 'total' demographic_segment: Segment for demographics: 'age', 'income', 'education', etc. location: Free-text place to limit to, resolved inline (e.g. 'California', 'Times Square', '1 mile from the Pentagon') in_geometry: Canonical geometry id(s) from a prior resolution (e.g. 'retail_area:abc,retail_area:def', 'cbsa:41860'); echoed as resolved_geometry co_located: If True, only compare in retail areas where ALL entities have locations Returns: Side-by-side comparison for the selected metric, plus 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"
delete_analysis
ChatGPTPermanently 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.
export_analysis
ChatGPTPrepare 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.
find_locations
ChatGPTFind locations matching criteria, as individual locations or aggregated counts. Provide at least one of: brand, category, location, in_geometry. Use full brand names, not abbreviations ('McDonalds' not 'MCD'). Args: brand: Brand name to filter by (e.g. 'Starbucks') category: Category filter (e.g. 'Coffee Shop', 'Clothing') location: Free-text place to search within, resolved inline (e.g. 'California', 'Times Square', '1 km from the Pentagon') in_geometry: Canonical geometry id(s) from a prior resolution — 'retail_area:<id>' for one mall, 'city:6000324' for a city, or a comma-separated union; echoed as resolved_geometry include_closed: If True, include closed locations (default False) limit: Max results per page (default 20, max 100) page: Page number for paginated results (default 1) page_size: Results per page; when set, overrides limit aggregate: None=list locations, 'brand'/'category'/'state'=count by that field Returns: Matching locations or aggregated counts, plus resolved_geometry. An ambiguous location returns candidates instead. Examples: Brand in an area: brand="Starbucks", location="Times Square, NYC" Category in a state: category="Clothing", location="California" Brands in a mall/area: in_geometry="retail_area:...", aggregate="brand" Near a point: category="Coffee Shop", location="1 km from 123 Main St" Count per state: category="Gym", aggregate="state"
get_analysis
ChatGPTOne 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_demographics
ChatGPTGet the visitor demographic breakdown (e.g. income brackets, age groups) for a brand, location, retail area, or category. Use full brand names, not abbreviations ('McDonalds' not 'MCD'). Args: target: Brand name (e.g. 'Starbucks'), location UUID, or retail area UUID target_type: 'brand', 'location', or 'retail_area' category: Category filter (e.g. 'Coffee Shop', 'Gym') dataset: Segment type: 'age', 'income', 'education', 'tenure', 'industry' location: Free-text place to scope to, resolved inline (e.g. 'California', 'Times Square', '1 mile from the Pentagon') in_geometry: Canonical geometry id(s) from a prior resolution (e.g. 'retail_area:abc', 'cbsa:41860'); echoed as resolved_geometry start_date: Start date (YYYY-MM-DD or natural language) end_date: End date (YYYY-MM-DD or natural language) comparison_type: 'total' for percentages, 'state'/'nation' for difference vs reference group_by: 'state', 'city', 'location', or 'brand' Returns: Demographic segments with percentages and resolved_geometry. An ambiguous location returns candidates instead. Examples: Brand: target="Starbucks", dataset="income" Location: target="abc-123", target_type="location", dataset="age" Category in an area: category="Gym", location="California", dataset="income" By state: target="Target", dataset="income", group_by="state"
get_info
ChatGPTGet detailed information about a brand, location, or retail area. Use full brand names, not abbreviations ('McDonalds' not 'MCD'). Args: target: Brand name (e.g. 'Starbucks'), location UUID, or retail area UUID target_type: 'brand', 'location', or 'retail_area' include_closed: If True, include closed locations in counts (default False) Returns: Entity metadata — location counts, categories, address, etc.
get_visits
ChatGPTGet 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. 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. An ambiguous location returns candidates instead of running the query. GROUP_BY (optional): omit for a time series; set to 'state', 'city', 'brand', 'location', 'category', or 'retail_area' for totals per group. Use full brand names, not abbreviations ('McDonalds' not 'MCD'). Args: target: Brand name (e.g. 'Starbucks'), comma-separated brand names, location UUID, or retail area UUID target_type: 'brand', 'location', or 'retail_area' category: Category filter (e.g. 'Coffee Shop', 'Clothing') location: Free-text place to scope to, resolved inline (e.g. 'California', 'Times Square', '1 mile from the Pentagon') in_geometry: Canonical geometry id(s) from a prior resolution — 'retail_area:<id>' for one mall, or a comma-separated union (e.g. a district 'retail_area:abc,retail_area:def', a metro 'cbsa:41860') co_brand: Only include locations in retail areas where this brand also exists start_date: Start date (YYYY-MM-DD or natural language) end_date: End date (YYYY-MM-DD or natural language) granularity: 'daily', 'weekly', 'monthly', or 'total' comparison_type: 'total' for raw visits, 'yoy' for year-over-year group_by: 'brand', 'state', 'city', 'category', 'location', or 'retail_area' sort_by: 'visits', 'name', or 'date' sort_order: 'desc' or 'asc' limit: Max results (default 50, max 500) page: Page number for pagination (default 1) page_size: Results per page; when set, enables pagination and overrides limit format: 'csv' (default), 'summary', or 'markdown' demographics: Optional demographic segment to include (e.g. 'income', 'age') Returns: Visit data (time series or grouped) plus resolved_geometry. Examples: Brand monthly: target="Starbucks", granularity="monthly" Per-state: target="Starbucks", group_by="state" In an area: category="Coffee Shop", location="1 km from Times Square, NYC" Multi-brand: target="Starbucks, Dunkin", group_by="brand" Reuse a resolved area: in_geometry="retail_area:abc,retail_area:def"
list_analyses
ChatGPTThe 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_client_fields
ChatGPTWhich 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.
resolve_location
ChatGPTResolve a free-text place (city, metro/region, neighborhood, colloquial area like 'the Bay Area', landmark, address, ZIP, or mall) to canonical geometry id(s) with its true boundary, name, centroid, and stats. Usually you do NOT need this first — find_locations, search_entities, get_visits, and get_demographics all accept a free-text location= and resolve it inline. Use resolve_location to disambiguate a place interactively before querying, or to get a reusable geometry_id to pass as in_geometry= across several follow-up calls. Ambiguous queries trigger an MCP elicitation pick-list resolved in-band, so a single call returns a resolved geography. Clients without elicitation support get status='ambiguous' with candidates instead. Handling the response: - status='resolved': use geometry_ids downstream (comma-join for composites). - status='ambiguous': present clarifying_question and candidates, then call again with the chosen candidate's geometry_id (and same session_id) or a more specific query (e.g. 'Springfield, MO'). - status='not_found': ask the user for a more specific description. Args: query: Place to resolve (e.g. 'the Bay Area', 'the mall in Culver City', 'Springfield', 'zip 75103') geometry_id: A geometry id from a prior candidate; resolves deterministically session_id: Opaque id echoed back to correlate a clarifying follow-up Returns: A ResolvedLocation with status, geometry_ids, name, centroid, area, place_count, and (when ambiguous) candidates + a clarifying question.
save_analysis
ChatGPTKeep results the user has already seen, under a name they choose, so they can be retrieved later without re-running or re-paying for the query. The analysis is stored by Passby, in the library belonging to this user's Passby account, and stays there across conversations and clients. Pass the handles of the results to keep — every tool response that produced data carries a saveable_as handle in its structured content. Do NOT pass rows, and do not re-describe the query: the handle already holds the question exactly as it was interpreted, so what is saved is the same city, the same period and the same brands the user was shown. An analysis can hold results from SEVERAL tool calls. If the user asked three questions and wants them kept together, pass all of their handles. A single call that produced several result sets — a comparison across brands, a year-over-year series — contributes all of them automatically. title is the user's own name for it, and must be unique in their library; a clash is refused and names what already holds it. narrative should carry the summary you just gave them, because that interpretation is most of what they think they are saving. Handles are for you, not for the user. Never show one or ask them to quote one — say what you are about to save in their own words instead. Returns: The analysis id, title, and each result with its label, row count and columns.
search_entities
ChatGPTResolve a fuzzy or partial NAME to a canonical brand, retail area, or category via semantic similarity — the entity analog of resolve_location. Use it before get_info / get_visits when you only have an approximate name ('coffee', 'the mall in Culver City'). Optionally pass location or in_geometry to restrict to entities present in an area. To COUNT brands or categories inside an area (not name-match), prefer find_locations(location=..., aggregate="brand"|"category"). Use this tool's 'retail_area' type to enumerate malls/centers in an area (no find_locations equivalent). Use full brand names, not abbreviations ('McDonalds' not 'MCD'). Args: query: Search text (e.g. 'coffee', 'Starbucks', 'mall in Seattle') entity_type: 'brand', 'retail_area', or 'category' location: Free-text place to restrict results to, resolved inline (e.g. 'Times Square', 'California', '1 mile from the Pentagon') in_geometry: Canonical geometry id(s) to restrict results to (e.g. 'retail_area:abc,retail_area:def', 'cbsa:41860') limit: Max results (default 10, max 20) Returns: Matching entities ranked by similarity, plus resolved_geometry. Examples: Coffee brands: query="coffee", entity_type="brand" Retail areas in an area: entity_type="retail_area", location="Pentagon City, VA" Named mall: query="Seattle mall", entity_type="retail_area" Category for a term: query="gym", entity_type="category"