LocationLists is an MCP server published by io.github.kylehawke-stack, hosted at locationlists.com. When last checked on 2026-11-21 it was working: it answers and lists its tools. It declares 18 tools, including search_datasets, relate_locations, count_by_area, cotenancy, get_dataset.
US business location data: search, sample, count, query rows or buy CSVs (Stripe or x402 USDC).
87 connections through 5 shared values. Tap any node.
Squares are this server's values; dots are other servers sharing them. A shared address or publisher is a lead, not proof of a common operator.
Inferred from the host name and headers: what a server runs on, not who runs it.
Find LocationLists datasets by brand, kind of business or industry (e.g. 'bobcat', 'restaurants', 'bank branches', 'dental practices', 'hardware stores'). Returns every matching dataset, best first, with slug, name, business type, industry, record count, coverage, whether it can be searched by distance (distanceSearch), and page URL. A kind of business or an industry in the query matches every dataset of that kind, and `kinds` names it as a category that count_locations can combine into one answer. Each brand or chain is its own dataset. After finding one you can filter it by city, state, zip, any column, or a radius around a place (e.g. within 25 miles of Los Angeles, CA) when it has coordinates: use count_locations for how many match, and get_sample with the same filters for that count plus the list's fixed free sample rows, each marked matches_your_question. Both are free. To cover several chains near one place, pass datasets or category and a total to count_locations, and you get one answer, one price and one file. kind "register" searches live public registers instead (a state's licensed child care, liquor licences, SNAP retailers…): each result's `source` is the key relate_locations takes as a set's opendata {source, state}, compared by distance (mode near). Registers are read live, never sold.
| Parameter | Type | Description |
|---|---|---|
| kind | string | list (default): the lists we sell. register: live public registers read from their publisher, e.g. {"query": "child care", "kind": "register", "state": "NY"} — each result's source goes in relate_locations as {"opendata": {"source": "<source>", "state": "NY"}}. |
| limit | integer | Max results (default: every match) |
| query | string | Free text: brand, kind of business, industry or product |
| state | string | With kind "register": prefer registers covering this state, e.g. "NY" |
| category | string | Restrict to one catalog category, industry or subcategory |
{
"name": "search_datasets",
"title": "Search location datasets",
"description": "Find LocationLists datasets by brand, kind of business or industry (e.g. 'bobcat', 'restaurants', 'bank branches', 'dental practices', 'hardware stores'). Returns every matching dataset, best first, with slug, name, business type, industry, record count, coverage, whether it can be searched by distance (distanceSearch), and page URL. A kind of business or an industry in the query matches every dataset of that kind, and `kinds` names it as a category that count_locations can combine into one answer. Each brand or chain is its own dataset. After finding one you can filter it by city, state, zip, any column, or a radius around a place (e.g. within 25 miles of Los Angeles, CA) when it has coordinates: use count_locations for how many match, and get_sample with the same filters for that count plus the list's fixed free sample rows, each marked matches_your_question. Both are free. To cover several chains near one place, pass datasets or category and a total to count_locations, and you get one answer, one price and one file. kind \"register\" searches live public registers instead (a state's licensed child care, liquor licences, SNAP retailers…): each result's `source` is the key relate_locations takes as a set's opendata {source, state}, compared by distance (mode near). Registers are read live, never sold.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"kind": {
"enum": [
"list",
"register"
],
"type": "string",
"description": "list (default): the lists we sell. register: live public registers read from their publisher, e.g. {\"query\": \"child care\", \"kind\": \"register\", \"state\": \"NY\"} — each result's source goes in relate_locations as {\"opendata\": {\"source\": \"<source>\", \"state\": \"NY\"}}."
},
"limit": {
"type": "integer",
"maximum": 1000,
"minimum": 1,
"description": "Max results (default: every match)"
},
"query": {
"type": "string",
"description": "Free text: brand, kind of business, industry or product"
},
"state": {
"type": "string",
"description": "With kind \"register\": prefer registers covering this state, e.g. \"NY\""
},
"category": {
"type": "string",
"description": "Restrict to one catalog category, industry or subcategory"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}Free. How one set of places relates to another, by straight-line distance. The base set is the usual dataset / datasets / category plus filters; relate.anchor is the other set, given the same way. Modes: nearest (each base row's k<=3 nearest anchors with miles), count_within (rank base rows by how many anchors are within radius_miles), within_any (base rows with at least one anchor within radius_miles), none_within (base rows with no anchor within radius_miles). Mode next_best (no anchor, needs the base set's state) ranks the candidate new sites in that state by how well they match what the base list's own locations typically have nearby, blended with an estimated market capture; every candidate names its matched factors. Mode typically_near answers "who is X typically located near?" — the profile: the kinds of place and brands the base list's locations have nearby far more often than a typical spot (share of locations, lift, average miles), with an `answer` sentence and a link to the ranked sites; state optional (without one it is computed in the list's top state and the answer says which); a thin sample is said, never sold. Every set (base, anchor) also takes metro (a CBSA code or name) or areas_in (county / ZIP / metro / state ids), like count_locations. Mode near / not_near matches by distance only (near_m metres, default 30) and is how a LIVE public register is compared: give a set as opendata {source, state} instead of a dataset — search_datasets with kind "register" finds the source key. A register is read at the moment you ask, never sold; the answer names its publisher, licence and read time. Returns counts for both sets (rows without coordinates are left out and counted), summary stats, up to 3 preview rows, the price of the full answer (base rows plus the anchor rows named, each at its dataset's per-row rate, one card fee) and how to buy it with query_locations or create_query_checkout using the same arguments. Example: {"dataset": "<slug>", "state": "VA", "relate": {"mode": "nearest", "k": 1, "anchor": {"dataset": "<other slug>", "metro": "Richmond"}}}. Profile: {"dataset": "<slug>", "relate": {"mode": "typically_near"}}. Live register: {"dataset": "ymca", "state": "NY", "relate": {"mode": "near", "near_m": 30, "anchor": {"opendata": {"source": "data.ny.gov/cb42-qumz", "state": "NY"}}}}.
| Parameter | Type | Description |
|---|---|---|
| zip |
Free, counts only. Counts places per county / zip / state / metro for 1 to 4 labeled sets (each a dataset, datasets or category plus filters), and compares them: has (areas with at least one of every listed set) and lacks (areas with none of any listed set). E.g. counties that have set a but no set b; ZIPs where a closure-filtered set exists and another set still has places. Rows that cannot be placed are counted, never read as zero. Every area row can carry Census / NOAA figures (area_columns) and the areas can be ranked by one of them or by a count (order_by), so markets rank by demand; limit + offset page through every matching area (page.total, page.nextOffset), or all: true lists every matching area in one answer; top_values shows what kinds of place make up each count. Warnings lead the answer when they change how it reads: a set that could not be counted is never a zero (no has/lacks answer uses it), a lacks set too thin to support absence (few places, or an open-data brand list below the brand's own count), and areas in states a set's lists do not cover (those rows carry notCovered: there 0 means not covered, not none there). notes explain placement (duplicates counted once, state column vs county). Reach: a set's `near` (the same shape count_locations takes) keeps only its rows within radius_miles of one point or of any of several `points`, before they are rolled up by area — so a regional operator is counted where it reaches, not nationally: "metros within 100 miles of these three offices" is by=metro with near={points:[…], radius_miles:100}. Drive time is not offered. FROM A CELL TO ITS ROWS: every area listed carries `rows` per set: the count, the price of those rows, a link, and `args` — the count_locations / query_locations / create_query_checkout call (the set's filters plus areas_in for that area) that returns exactly them, so a count cell is one call from its named rows. with_sample: true adds, on the first areas listed, the free preview behind each cell — the list's fixed published sample rows that fall inside the area, marked matches_your_question (never a sample of the area's places). Example: {"by": "county", "sets": [{"label": "a", "dataset": "<slug>"}, {"label": "b", "dataset": "<other slug>"}], "has": ["a"], "lacks": ["b"], "in_state": "VA"}. Ranked by demand: {"by": "county", "sets": [{"label": "a", "dataset": "<slug>"}], "area_columns": ["county:population,median_household_income"], "order_by": {"field": "population"}, "limit": 100, "offset": 100}. Regional: {"by": "metro", "sets": [{"label": "ours", "dataset": "<slug>", "near": {"points": [{"place": "Richmond, VA"}, {"place": "Norfolk, VA"}], "radius_miles": 100}}]}.
Free, counts only. How two sets of places sit together: the share of set a within radius_miles of set b and of b within radius_miles of a, how many places overlap, and the county / zip / state / metro areas that have both, only a, or only b (top 10 of each named). Each set is a dataset, datasets or category plus filters, the same as count_locations; any US brand or kind of place works, including Overture lists from search_datasets. Example: {"a": {"dataset": "<slug>"}, "b": {"dataset": "<other slug>"}, "radius_miles": 1, "by": "county"}.
| Parameter | Type | Description |
|---|---|---|
| a * | object | First set: dataset, datasets or category, plus filters |
| b * | object | Second set, given the same way |
| by | string | Area unit for both/only-a/only-b (default county) |
| in_state | string | Only areas in this state |
| radius_miles | number | Distance that counts as together (default 1 mile) |
{
"name": "cotenancy",
"title": "Cotenancy between two sets (free)",
"description": "Free, counts only. How two sets of places sit together: the share of set a within radius_miles of set b and of b within radius_miles of a, how many places overlap, and the county / zip / state / metro areas that have both, only a, or only b (top 10 of each named). Each set is a dataset, datasets or category plus filters, the same as count_locations; any US brand or kind of place works, including Overture lists from search_datasets. Example: {\"a\": {\"dataset\": \"<slug>\"}, \"b\": {\"dataset\": \"<other slug>\"}, \"radius_miles\": 1, \"by\": \"county\"}.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"a",
"b"
],
"properties": {
"a": {
"type": "object",
"properties": {
"zip": {
"type": "string"
},
"city": {
"type": "string"
},
"near": {
"type": "object",
"properties": {
"lat": {
"type": "number"
},
"lng": {
"type": "number"
},
"zip": {
"type": "string",
"description": "5-digit zip"
},
"place": {
"type": "string",
"description": "City or town with state, e.g. \"Topeka, KS\""
},
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"lat": {
"$ref": "#/properties/a/properties/near/properties/lat"
},
"lng": {
"$ref": "#/properties/a/properties/near/properties/lng"
},
"zip": {
"$ref": "#/properties/a/properties/near/properties/zip"
},
"place": {
"$ref": "#/properties/a/properties/near/properties/place"
}
},
"additionalProperties": false
},
"maxItems": 10,
"minItems": 1,
"description": "Several points instead of one place/zip/lat+lng (at most 10): a row counts when it is within the radius of ANY of them, e.g. an operator's offices."
},
"radius_miles": {
"type": "number",
"maximum": 500,
"description": "Only rows within this straight-line distance of the point (or of any of the points). Free.",
"exclusiveMinimum": 0
}
},
"description": "Distance search on lists with coordinates: one of place, zip, lat+lng or points, with radius_miles.",
"additionalProperties": false
},
"metro": {
"type": "string",
"description": "Only rows in one metro area (CBSA): its 5-digit code (\"37980\") or its name (\"Philadelphia\", \"Philadelphia, PA\"). The same as areas_in {\"by\": \"metro\", \"ids\": [code]}."
},
"state": {
"type": "string"
},
"where": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"op"
],
"properties": {
"op": {
"enum": [
"eq",
"ne",
"gt",
"gte",
"lt",
"lte",
"in",
"contains",
"starts_with",
"is_blank",
"not_blank",
"not_contains",
"not_in",
"any_of"
],
"type": "string"
},
"field": {
"type": "string"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "array",
"items": {
"type": [
"string",
"number"
]
}
}
]
},
"any_of": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"op"
],
"properties": {
"op": {
"enum": [
"eq",
"ne",
"gt",
"gte",
"lt",
"lte",
"in",
"contains",
"starts_with",
"is_blank",
"not_blank",
"not_contains",
"not_in",
"any_of"
],
"type": "string"
},
"field": {
"type": "string"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "array",
"items": {
"type": [
"string",
"number"
]
}
}
]
}
},
"additionalProperties": false
},
"maxItems": 12
}
},
"additionalProperties": false
},
"maxItems": 12
},
"county": {
"type": "string"
},
"dataset": {
"type": "string"
},
"exclude": {
"type": "array",
"items": {
"type": "string"
},
"description": "Dataset slugs left out wherever the set expands: a category minus one of its members (a list's competitors are its own category with itself excluded)."
},
"areas_in": {
"type": "object",
"required": [
"by",
"ids"
],
"properties": {
"by": {
"enum": [
"county",
"zip",
"state",
"metro"
],
"type": "string"
},
"ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 200,
"minItems": 1,
"description": "County FIPS, 5-digit ZIP, CBSA code or state code — the `id` of a count_by_area row"
}
},
"description": "Only rows in these areas, e.g. {\"by\": \"county\", \"ids\": [\"51760\"]} for Richmond city, VA — the ids count_by_area returns, placed the same way (/find: areas_in=county:51760).",
"additionalProperties": false
},
"category": {
"type": "string"
},
"datasets": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
},
"opendata": {
"type": "object",
"required": [
"source"
],
"properties": {
"zips": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Or cut it to 5-digit ZIP codes, e.g. [\"78114\", \"78154\"] (/find: opendata_zips=78114,78154)"
},
"state": {
"type": "string",
"description": "Cut the register to one state, e.g. \"NY\" (/find: opendata_state=NY)"
},
"where": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 12,
"description": "Conditions on the register's own columns, each \"column:op:value\" with op eq | starts_with | contains | not_blank, e.g. [\"license_status:starts_with:Active\"] (/find: opendata_where=)"
},
"source": {
"type": "string",
"description": "The register's key, \"<domain>/<id>\" — search_datasets with kind \"register\" finds it, e.g. \"data.ny.gov/cb42-qumz\" (New York's licensed child-care programs)"
}
},
"description": "Instead of dataset / datasets / category: a public register read live from its publisher at question time (e.g. a state's licensed child-care programs). Matched by distance only (relate.mode near / not_near, near_m metres). Not a list we sell: the answer names the publisher, licence and read time, and prices only the rows of our lists.",
"additionalProperties": false
},
"area_where": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 6,
"description": "Only rows whose county/zip/state/metro meets a Census condition, each as \"<kind>:<attribute><op><value>\" (ops > >= < <= =; values accept 1M, 250k, $50,000, 10%), e.g. \"county:population>1000000\". Every clause must hold; the fact is the area's, not the row's, and it adds nothing to the price. Attributes: e.g. population, households, median_household_income, median_age, pct_65_plus, housing_units; Census ACS people, income, education and housing; businesses and jobs by NAICS sector (<sector>_establishments, <sector>_employees) or detailed code (naics_<code>_establishments / _employees / _payroll); population growth; NOAA climate normals and actuals; NOAA storm events; station weather normals; hourly weather normals; building stock; Zillow home values; Zillow rents; building permits; IRS tax returns; FEMA hazard risk; USDA farm census. Every key (11,012) with its label, unit and kinds: see /area-attributes.json."
},
"area_columns": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 6,
"description": "Census, NOAA, FEMA and USDA facts added to every row as columns named <kind>_<attribute>, each as \"<kind>:<attribute>,<attribute>\", e.g. \"county:population,median_household_income\" — the county / ZIP / metro / state figures beside each location, in the preview and in the file you buy, after the area's id and name (county_fips, county_name; zip_code; metro_cbsa, metro_name; state_code, state_name). Free. The same attribute words area_where takes (listed there)."
}
},
"description": "First set: dataset, datasets or category, plus filters",
"additionalProperties": false
},
"b": {
"type": "object",
"properties": {
"zip": {
"$ref": "#/properties/a/properties/zip"
},
"city": {
"$ref": "#/properties/a/properties/city"
},
"near": {
"$ref": "#/properties/a/properties/near"
},
"metro": {
"$ref": "#/properties/a/properties/metro"
},
"state": {
"$ref": "#/properties/a/properties/state"
},
"where": {
"$ref": "#/properties/a/properties/where"
},
"county": {
"$ref": "#/properties/a/properties/county"
},
"dataset": {
"$ref": "#/properties/a/properties/dataset"
},
"exclude": {
"$ref": "#/properties/a/properties/exclude"
},
"areas_in": {
"$ref": "#/properties/a/properties/areas_in"
},
"category": {
"$ref": "#/properties/a/properties/category"
},
"datasets": {
"$ref": "#/properties/a/properties/datasets"
},
"opendata": {
"$ref": "#/properties/a/properties/opendata",
"description": "Instead of dataset / datasets / category: a public register read live from its publisher at question time (e.g. a state's licensed child-care programs). Matched by distance only (relate.mode near / not_near, near_m metres). Not a list we sell: the answer names the publisher, licence and read time, and prices only the rows of our lists."
},
"area_where": {
"$ref": "#/properties/a/properties/area_where"
},
"area_columns": {
"$ref": "#/properties/a/properties/area_columns"
}
},
"description": "Second set, given the same way",
"additionalProperties": false
},
"by": {
"enum": [
"county",
"zip",
"state",
"metro"
],
"type": "string",
"description": "Area unit for both/only-a/only-b (default county)"
},
"in_state": {
"type": "string",
"description": "Only areas in this state"
},
"radius_miles": {
"type": "number",
"maximum": 250,
"description": "Distance that counts as together (default 1 mile)",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}Full record for one dataset: fields with descriptions, record and state counts, coverage measured on the rows (a list in 14 states says "partial U.S.: 14 states"; coverageDetail lists the states, rows per state and the states with none), whether it can be searched by distance, advertised refresh cadence and the real last-modified date of the file, FAQs, sample URL and the dataset's page on locationlists.com.
| Parameter | Type | Description |
|---|---|---|
| slug * | string | Dataset slug from search_datasets, e.g. bobcat-dealers |
{
"name": "get_dataset",
"title": "Get dataset details",
"description": "Full record for one dataset: fields with descriptions, record and state counts, coverage measured on the rows (a list in 14 states says \"partial U.S.: 14 states\"; coverageDetail lists the states, rows per state and the states with none), whether it can be searched by distance, advertised refresh cadence and the real last-modified date of the file, FAQs, sample URL and the dataset's page on locationlists.com.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"slug"
],
"properties": {
"slug": {
"type": "string",
"description": "Dataset slug from search_datasets, e.g. bobcat-dealers"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}Free. How many rows of one dataset match a filter — on geography and any other column (e.g. nonprofits with revenue_amt gt 2000000, dealers with dealerClass eq 'Elite'). Also reports how many rows were excluded only because a tested column was blank, so a thin column is not mistaken for a small answer; a small or empty answer says how many rows each condition removed and what the column really holds. Returns the exact card price of the matching rows, a link where the user can see and buy them, and the same rows in a cheaper list when one has them. Works for geography: city, state, county, zip, metro (a CBSA code or name: "all hospitals in the Philadelphia metro" is one call), areas_in (the county / ZIP / metro / state ids count_by_area returns), or `near` a place ("Los Angeles, CA"), zip or lat/lng within radius_miles, on lists with coordinates. AREA DATA, free: area_where keeps rows whose county / ZIP / metro / state meets a condition on a Census, weather, housing-market or tax-return figure (county:population>1000000, zip:typical_home_value>500000, zip:share_income_200k_plus>20), and area_columns adds those figures to every row as columns (county:population,median_household_income,typical_rent,average_adjusted_gross_income). COVERAGE: a list's coverage is measured on its rows (get_dataset coverageDetail: states and rows per state); a state the list has no rows in is said as not covered, never as none there. get_sample takes the same filters and returns the count plus the list's fixed free sample rows, marked matches_your_question. The result's `next` says exactly how to get every matching row. To cover several chains near one place, pass datasets or category (e.g. "retail" or "restaurant") and a total instead of dataset: one answer with counts per dataset, duplicates removed and up to 3 preview rows, one price and one file. Use get_dataset first for the column names. Scans the live file, so it can take several seconds on large datasets. Every number in the result is named: matched (rows meeting every filter), rowsRead (how many rows of the list were read to answer: the whole file for one of our lists, or, for an Overture list, only the index shards the question's area or place touches — so it can be far smaller than the list), maxRowsPerCall (the most rows one paid call returns), excludedBlank (rows dropped only because a tested column was blank), and price (soldBy says whether the list is sold as a file, by the row, or both; perRowUsd and perCallFeeUsd are the by-the-row terms, wallet the total a self-paying agent pays, breakdown each row source at its rate). To price exactly what one query_locations call returns — "the 10 nearest" — pass the same limit (and offset / order_by): `slice` then has that call's exact amount line by line and the card price of the same rows. A paid call is billed for the rows it returns: each row at its own list's per-row rate (an Overture open-data row at $0.005; a row of a chain LocationLists sells its own list for, at that list's rate), plus a $0.01 per-call fee, rounded once to the nearest cent, at least $0.02, never more than the whole list. count_locations with the same filters, limit and offset quotes exactly that page, row source by row source (price.breakdown), before anything is paid.
Free. Real rows from the live file, as JSON plus CSV text. Show these to the user so they can judge the fields and quality. Without filters: up to 10 rows spread across the whole dataset. With filters (the same ones count_locations takes: city, state, county, zip, metro, `where` on any column, areas_in (county / ZIP / metro / state ids from count_by_area), area_where, area_columns (Census figures as columns on every row), or `near` a place such as {place: "Los Angeles, CA", radius_miles: 25} on lists with coordinates): how many rows match, plus the list's FIXED free sample rows — the same published rows whatever the filter, each marked matches_your_question, the ones this filter matched FIRST (default 3 rows; rows up to the published sample's size shows them all, and samplePublished / sampleMatched say how many that is) — so the user can see real stores and the real column shape before deciding, with the exact count and price of the matches. The rows shown are fixed per list so that free answers cannot be composed into the file; the count, the coverage, the columns and the price are exact for the filter. To see what KINDS of place make up a count in an area (dealers vs manufacturers, say), use count_by_area with top_values on a class column. The result's `next` says exactly how to get every matching row. To preview several chains at once, pass datasets or category (e.g. "retail" or "restaurant") instead of slug: one combined answer with counts per dataset, duplicates removed and up to 3 rows across them. shape: hubspot | salesforce returns the same rows with that CRM's import column names first (the exact header row the paid file will have with the same shape), every other column after.
| Parameter | Type | Description |
|---|---|---|
| zip | string | Shortcut for where zip eq <value> |
| city | string | Shortcut for where city eq <value> |
| near | object | Distance search on lists with map coordinates (distanceSearch in search results): one of place, zip, lat+lng or `points` (within reach of any of them). Rows come back nearest first with a distance_miles column (straight line; no drive time); limit for 'the 10 closest', radius_miles for 'everything w… |
Ask LocationLists to add a list we do not have yet. Use it when search_datasets finds nothing that fits, or the user wants a brand, place or kind of business we do not publish. Before calling: ask the user whether to send the request, and ask for their email so we can tell them when the list is ready. Pass an email only if the user gave it to you in this conversation; never guess or invent one. Called with neither email nor email_declined, it sends nothing and asks for the email. The request goes to the LocationLists team, the same place as the request box on locationlists.com. We add new datasets every day and prioritize requested ones; there is no promised date. Free, nothing is charged.
| Parameter | Type | Description |
|---|---|---|
| name | string | The user's name, if they gave it |
| string | The user's email, only if they gave it, so we can tell them when the list is ready | |
| topic * | string | The list the user wants, in their words (2-200 characters) |
| company | string | The user's company, if they gave it |
| details | string | Anything else they specified: places, fields needed (phone, website, email), timing |
| use_case | string | What they will use the list for, if they said (e.g. sales outreach, territory planning) |
| email_declined | boolean | True only when you asked the user for their email and they chose not to leave one |
Send a message to the LocationLists team: wrong or missing data in a dataset, something that did not work, a pricing question, an idea, or anything else. Ask the user before sending and use their words. Ask for their email so the team can reply, and pass it only if they gave it; never guess or invent one. Called with neither email nor email_declined, it sends nothing and asks for the email. Free.
| Parameter | Type | Description |
|---|---|---|
| string | The user's email, only if they gave it | |
| dataset | string | Dataset slug it concerns, if any, e.g. generac-dealers |
| message * | string | The feedback, in the user's words (5-4000 characters) |
| category | string | What it is about (default other) |
| email_declined | boolean | True only when you asked the user for their email and they chose not to leave one |
{
"name": "send_feedback",
"title": "Send feedback",
"description": "Send a message to the LocationLists team: wrong or missing data in a dataset, something that did not work, a pricing question, an idea, or anything else. Ask the user before sending and use their words. Ask for their email so the team can reply, and pass it only if they gave it; never guess or invent one. Called with neither email nor email_declined, it sends nothing and asks for the email. Free.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"message"
],
"properties": {
"email": {
"type": "string",
"description": "The user's email, only if they gave it"
},
"dataset": {
"type": "string",
"description": "Dataset slug it concerns, if any, e.g. generac-dealers"
},
"message": {
"type": "string",
"description": "The feedback, in the user's words (5-4000 characters)"
},
"category": {
"enum": [
"bug",
"data quality",
"pricing",
"feature",
"other"
],
"type": "string",
"description": "What it is about (default other)"
},
"email_declined": {
"type": "boolean",
"description": "True only when you asked the user for their email and they chose not to leave one"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}
}For a user who HAS a list of business locations and wants to sell it on LocationLists. Nothing is stored and nothing is charged. Give what the list is (one sentence), about how many rows, and the figure they have in mind in US dollars: the result says whether it holds up against what lists that size sell for here and the closest lists already on the site, what the seller would keep (80%), and what we would list it at (list prices end in 9). Then sell_list hands the file over. The same check in a browser: https://locationlists.com/sell.
| Parameter | Type | Description |
|---|---|---|
| rows * | integer | About how many rows (locations) the list has |
| what * | string | What the list is, in the user's words: 'Florida marinas with slip counts, from marina websites and county records' |
| target_usd * | number | The price the user has in mind for the whole file, US dollars |
{
"name": "price_my_list",
"title": "Price a list the user wants to sell",
"description": "For a user who HAS a list of business locations and wants to sell it on LocationLists. Nothing is stored and nothing is charged. Give what the list is (one sentence), about how many rows, and the figure they have in mind in US dollars: the result says whether it holds up against what lists that size sell for here and the closest lists already on the site, what the seller would keep (80%), and what we would list it at (list prices end in 9). Then sell_list hands the file over. The same check in a browser: https://locationlists.com/sell.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"what",
"rows",
"target_usd"
],
"properties": {
"rows": {
"type": "integer",
"minimum": 1,
"description": "About how many rows (locations) the list has"
},
"what": {
"type": "string",
"maxLength": 400,
"minLength": 3,
"description": "What the list is, in the user's words: 'Florida marinas with slip counts, from marina websites and county records'"
},
"target_usd": {
"type": "number",
"maximum": 5000,
"minimum": 1,
"description": "The price the user has in mind for the whole file, US dollars"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}Put the user's list of business locations up for sale on LocationLists. They keep 80% of each sale; we host, check out, deliver and pay out. No account. The steps, each one call: (1) call with the user's email alone: a six-digit code is emailed to them (ask the user for their email first; never invent one). (2) Ask the user for the code from that email (never guess it) and call again with email, code, and the list: `rows` inline, an array of objects, one per location, with a name and an address or latitude/longitude (up to 5,000 rows), or for a bigger file `filename` + `bytes` and no rows, which returns an upload_url (HTTP PUT the raw file to it) and a token. (3) After the PUT, call with token, upload_id and filename. Add what (one sentence), rows_claimed and target_usd from price_my_list when you have them. Several lists: up to 10 in one call as `lists` (each item: what, rows_claimed, target_usd, and rows inline or filename + bytes), then one call with token and `uploads` for the files you PUT; each list becomes its own listing. Where the list came from: the seller terms (https://locationlists.com/sell#terms) ask that the seller owns the list or has the right to sell it, and that it holds no personal data about private individuals. Mention the terms link once, in passing, before the file moves; sending the list is their agreement to them. No checklist and no confirmation step: a person at LocationLists reviews every file before it goes live, so the assistant's part is to point at the terms, not to investigate. Then everything is by email to the seller: the written listing with its checks and price in a few minutes, Confirm / Change links, and 'It's live' after LocationLists reviews it. Accepted: CSV, TSV, JSON, GeoJSON; not Excel (save as CSV UTF-8 first). Nothing goes live without the seller's confirmation and a human review. The same thing in a browser: https://locationlists.com/sell.
| Parameter | Type | Description |
|---|---|---|
| code | string | The six-digit code from the email we sent, as the user read it to you |
| rows | array | The list itself, one object per location, up to 5,000. Keep the user's own column names. |
| what | string |
Free. Emails the user a plain-English quote for exactly this request: how many rows match, the card price, a few of the matches and a card checkout link, so they can pay later, from any device, or forward it to whoever holds the card. Takes the same arguments as count_locations: dataset, or datasets / category with total, plus filters. Before calling: ask the user for their email and whether to send it. Pass an email only if the user gave it to you in this conversation; never guess or invent one. Nothing is charged and nothing is bought; the price is checked again when they open the link.
| Parameter | Type | Description |
|---|---|---|
| zip | string | Shortcut for where zip eq <value> |
| city | string | Shortcut for where city eq <value> |
| near | object | Distance search on lists with map coordinates (distanceSearch in search results): one of place, zip, lat+lng or `points` (within reach of any of them). Rows come back nearest first with a distance_miles column (straight line; no drive time); limit for 'the 10 closest', radius_miles for 'everything w… |
| email * | string | The user's email, as they gave it |
| metro | string | Only rows in one metro area (CBSA): its 5-digit code ("37980") or its name ("Philadelphia", "Philadelphia, PA"). The same as areas_in {"by": "metro", "ids": [code]}: rows are placed the way count_by_area places them, so "all hospitals in the Philadelphia metro" is one count, one price and one purcha… |
| state | string | Shortcut for where state eq <value>. Two-letter code; several states comma-separated ("VA,NC,SC") are one `in`. |
Line-item prices and total for a list of dataset slugs, each with how it is sold (soldBy: file, row, or both) — the same rule create_checkout, buy_dataset, create_query_checkout and query_locations enforce, so a quote never offers a route checkout refuses. A list sold by the row only (an Overture Maps list) is quoted at its per-row rate with the route named, not as a file; count_locations with filters gives the exact price of the rows. Every list sold by the row is quoted with its perRow rate and the per-call fee, next to any file price. A paid call is billed for the rows it returns: each row at its own list's per-row rate (an Overture open-data row at $0.005; a row of a chain LocationLists sells its own list for, at that list's rate), plus a $0.01 per-call fee, rounded once to the nearest cent, at least $0.02, never more than the whole list. count_locations with the same filters, limit and offset quotes exactly that page, row source by row source (price.breakdown), before anything is paid. How a list is sold: our own lists are sold as a whole file (create_checkout / buy_dataset), and those of 5,000 records or more are also sold by the row (query_locations / create_query_checkout); smaller lists are sold whole only. Open map data lists (soldBy "row" in get_dataset) are sold by the row only, at any size — there is no file to buy. One card checkout downloads up to 10,000 rows at once; up to 150,000 rows, an answer's buy link still sells them all, and the file is built after payment and its download link emailed. For more, buy the whole file where the list has one, narrow the question to a state, metro or area, or email kyle@locationlists.com for the whole file. If a bundle covers several requested brands for less, it says so.
| Parameter | Type | Description |
|---|---|---|
| slugs * | array | Dataset slugs |
{
"name": "get_quote",
"title": "Price one or more datasets",
"description": "Line-item prices and total for a list of dataset slugs, each with how it is sold (soldBy: file, row, or both) — the same rule create_checkout, buy_dataset, create_query_checkout and query_locations enforce, so a quote never offers a route checkout refuses. A list sold by the row only (an Overture Maps list) is quoted at its per-row rate with the route named, not as a file; count_locations with filters gives the exact price of the rows. Every list sold by the row is quoted with its perRow rate and the per-call fee, next to any file price. A paid call is billed for the rows it returns: each row at its own list's per-row rate (an Overture open-data row at $0.005; a row of a chain LocationLists sells its own list for, at that list's rate), plus a $0.01 per-call fee, rounded once to the nearest cent, at least $0.02, never more than the whole list. count_locations with the same filters, limit and offset quotes exactly that page, row source by row source (price.breakdown), before anything is paid. How a list is sold: our own lists are sold as a whole file (create_checkout / buy_dataset), and those of 5,000 records or more are also sold by the row (query_locations / create_query_checkout); smaller lists are sold whole only. Open map data lists (soldBy \"row\" in get_dataset) are sold by the row only, at any size — there is no file to buy. One card checkout downloads up to 10,000 rows at once; up to 150,000 rows, an answer's buy link still sells them all, and the file is built after payment and its download link emailed. For more, buy the whole file where the list has one, narrow the question to a state, metro or area, or email kyle@locationlists.com for the whole file. If a bundle covers several requested brands for less, it says so.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"slugs"
],
"properties": {
"slugs": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 50,
"minItems": 1,
"description": "Dataset slugs"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}Opens a Stripe Checkout session for one dataset and returns the payment URL plus the session id. Give the URL to the user to pay (card, Apple Pay, Google Pay). After payment Stripe emails them a permanent download link; use check_order with the session id to confirm and fetch it. Does not charge anything by itself.
| Parameter | Type | Description |
|---|---|---|
| slug * | string | Dataset slug |
| string | Buyer email, if known — prefills Checkout and is where the download link is sent |
{
"name": "create_checkout",
"title": "Create a checkout link",
"description": "Opens a Stripe Checkout session for one dataset and returns the payment URL plus the session id. Give the URL to the user to pay (card, Apple Pay, Google Pay). After payment Stripe emails them a permanent download link; use check_order with the session id to confirm and fetch it. Does not charge anything by itself.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"slug"
],
"properties": {
"slug": {
"type": "string",
"description": "Dataset slug"
},
"email": {
"type": "string",
"format": "email",
"description": "Buyer email, if known — prefills Checkout and is where the download link is sent"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}
}Given a Stripe Checkout session id (cs_…), reports whether it is paid and, if so, returns the permanent download link for the CSV. Works for whole files, filtered rows and combined (several-dataset) orders. Any download link takes ?shape=hubspot or ?shape=salesforce for CRM-ready column names (every column kept).
| Parameter | Type | Description |
|---|---|---|
| sessionId * | string | Checkout session id from create_checkout |
{
"name": "check_order",
"title": "Check order status",
"description": "Given a Stripe Checkout session id (cs_…), reports whether it is paid and, if so, returns the permanent download link for the CSV. Works for whole files, filtered rows and combined (several-dataset) orders. Any download link takes ?shape=hubspot or ?shape=salesforce for CRM-ready column names (every column kept).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"sessionId"
],
"properties": {
"sessionId": {
"type": "string",
"pattern": "^cs_",
"description": "Checkout session id from create_checkout"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}For buyers paying by card: opens a Stripe Checkout for just the rows of one dataset that match a filter, and returns the payment URL to give the user. Takes the same filters as count_locations (state/city/county/zip, `where` on any column, `near`, `order_by`) and up to 10,000 rows. It counts the matches first, so the buyer pays only for rows that exist: the data price is the same per-row price query_locations charges, plus a card processing fee (2.9% + $0.30) added on top, one price the buyer sees at checkout. After payment the buyer is emailed a CSV download link; check_order with the session id returns it too. No match, a bad column, a distance search on a list without coordinates, or a subset that would cost more than the whole file returns an explanation and creates no checkout — nothing is charged. An agent that pays for itself should call query_locations instead. To cover several chains near one place, pass datasets or category and a total instead of dataset: one answer, one price and one checkout for one CSV (source_dataset names each row's dataset, duplicates removed). shape: hubspot | salesforce delivers the CSV with that CRM's import column names first (the download link also takes ?shape= later).
| Parameter | Type | Description |
|---|---|---|
| zip | string | Shortcut for where zip eq <value> |
| city | string | Shortcut for where city eq <value> |
| near | object | Distance search on lists with map coordinates (distanceSearch in search results): one of place, zip, lat+lng or `points` (within reach of any of them). Rows come back nearest first with a distance_miles column (straight line; no drive time); limit for 'the 10 closest', radius_miles for 'everything w… |
| string | Buyer email, if known — prefills Checkout and is where the download link is sent | |
| limit | integer |
Return matching rows from one dataset, filtered on any of its columns — state/city/county/zip shortcuts plus `where` conditions with numeric comparisons (e.g. [{field:"revenue_amt",op:"gt",value:2000000}]), sorted with `order_by` and paged with `offset`. `near` ({place:"Topeka, KS"}, a zip, or lat+lng, optional radius_miles) returns the closest rows first with distance_miles, on lists with coordinates — so "10 banks closest to Topeka" is one call for 10 rows. get_dataset lists the columns; count_locations (free) tells you how many rows match and what fetching them costs before you pay. Priced per row and settled only after the rows are produced, so a failed call costs nothing. The rate is derived from the dataset: roughly 2x its list price spread over its record count, so a small slice of a big file is cents. By default you get and pay for every matching row, up to 100 to 1,000 rows per call depending on how wide the dataset's rows are (count_locations reports maxRowsPerCall); pass limit for fewer. Call it without payment first: the result is a payment-required quote (terms in the server instructions) with the exact amount and `quote` (the same rows, each source at its rate, as count_locations' slice), and nothing is charged until you retry with payment. A paid call is billed for the rows it returns: each row at its own list's per-row rate (an Overture open-data row at $0.005; a row of a chain LocationLists sells its own list for, at that list's rate), plus a $0.01 per-call fee, rounded once to the nearest cent, at least $0.02, never more than the whole list. count_locations with the same filters, limit and offset quotes exactly that page, row source by row source (price.breakdown), before anything is paid. How a list is sold: our own lists are sold as a whole file (create_checkout / buy_dataset), and those of 5,000 records or more are also sold by the row (query_locations / create_query_checkout); smaller lists are sold whole only. Open map data lists (soldBy "row" in get_dataset) are sold by the row only, at any size — there is no file to buy. One card checkout downloads up to 10,000 rows at once; up to 150,000 rows, an answer's buy link still sells them all, and the file is built after payment and its download link emailed. For more, buy the whole file where the list has one, narrow the question to a state, metro or area, or email kyle@locationlists.com for the whole file. To cover several chains near one place, pass datasets or category and a total (up to 1,000 rows) instead of dataset: one answer, one price and one file, with source_dataset naming each row's dataset and duplicates removed; inside a combined answer, small datasets are sold by the row too.
Buy an entire dataset outright and get a permanent download link for the CSV. Pays once, at the same list price a human pays by card — no account and no checkout page.\n\nPrefer this over repeated query_locations calls whenever you want most of a file. Metered queries are priced per row and deliberately cost more than the file if you assemble it that way, so past a few hundred rows buying outright is both cheaper and complete. get_dataset (free) gives the price and record count first.
| Parameter | Type | Description |
|---|---|---|
| dataset * | string | Dataset slug, e.g. generac-dealers. Use search_datasets first. |
{
"name": "buy_dataset",
"title": "Buy a complete dataset (paid)",
"description": "Buy an entire dataset outright and get a permanent download link for the CSV. Pays once, at the same list price a human pays by card — no account and no checkout page.\\n\\nPrefer this over repeated query_locations calls whenever you want most of a file. Metered queries are priced per row and deliberately cost more than the file if you assemble it that way, so past a few hundred rows buying outright is both cheaper and complete. get_dataset (free) gives the price and record count first.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"dataset"
],
"properties": {
"dataset": {
"type": "string",
"description": "Dataset slug, e.g. generac-dealers. Use search_datasets first."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}
}No connector needed: any AI assistant can answer a location question by opening https://locationlists.com/find?q=<the question in plain words> — counts, a preview, a price and a card checkout link. Connect the MCP for repeat use or wallet payments. LocationLists sells ready-to-use CSV datasets of US (and some Canadian) business locations — every dealer, store, nonprofit, bank branch or contractor a source publishes. NO SETUP NEEDED: every question these tools answer also has a plain web link that any assistant able to open a page can use, with no connector, account or key: https://locationlists.com/find?dataset=<slug>&near=<place or zip>&radius=<miles> (state=, city=, zip=, where=<column>:<op>:<value>; category= or datasets= to combine lists; total=<rows>). It returns the count, up to 3 fixed sample rows of the lists involved, the price and a Buy link. A connector is never required to get an answer; a one-off question works from the /find link. When a question is genuinely ambiguous the /find answer (and the JSON's `clarification` field) still carries the best-guess answer, plus a few complete links that each settle one reading: ask your user which they meant, or proceed on the best guess. FREE tools: search_datasets to find datasets (by brand, kind of business or industry), get_dataset for the full record and its filterable columns, get_sample for real rows, and count_locations to count rows matching filters on any column — revenue, employees, category, dealer tier, not just geography — with the exact price of the matching rows. Link twins: search_datasets = https://locationlists.com/find?search=<words>; get_dataset = https://locationlists.com/data/<slug>/dataset.json; count_locations and get_sample = https://locationlists.com/find?dataset=<slug>&<filters>. relate_locations compares two lists by distance (link twin: https://locationlists.com/find?dataset=<slug>&relate=nearest&k=1&b.dataset=<other slug>). count_by_area counts places per county, ZIP, state or metro for up to 4 lists, with has / lacks (link twin: https://locationlists.com/find?areas=county&dataset=<slug>&b.dataset=<other slug>&has=a&lacks=b). Both are free. Every result starts with `answer` (and often `next`): plain words and a link, written for a business reader. The `technicalDetails` field carries tool names, arguments and payment terms for developers and AI agents; anyone may read it. AUTONOMOUS PURCHASE (no account, no human): paid tools settle in USDC on Base via x402. Call count_locations first for the exact cost. query_locations returns the matching rows, priced per row (every match by default); buy_dataset buys the whole file and returns a permanent CSV download link. Calling a paid tool without payment returns a tool result with isError:true whose structuredContent is the x402 PaymentRequired (exact amount, payTo, asset); retry the same call with the signed PaymentPayload in params._meta["x402/payment"]. Failed or empty calls cost nothing. GEOGRAPHY: filter by radius, city or zip with count_locations and get_sample before buying — e.g. near {place: "Los Angeles, CA", radius_miles: 25} on a list with map coordinates (search results say distanceSearch), or city/state/zip, or `where` on any column. count_locations gives the exact number of matches; get_sample with the same filters returns that count plus the list's fixed free sample rows, each marked `matches_your_question` — the same rows whatever the filter, so they show the real column shape, not a sample of the matches. Both are free, and both return `next`, which says how to get every matching row. Each brand or chain is its own dataset. To cover a kind of business near one place ("200 restaurants near Chicago"), pass category (a kind of business, an industry, or "retail") or datasets (a list of slugs) and total instead of dataset: count_locations and get_sample then give one combined answer (counts per dataset, duplicates removed, a preview, one price), and `next` says how to get the rows as one fil
Names, descriptions and schemas were written by the server and are shown as data.
Pattern matches on what the server declares. They show what it says it can do, not what it does.
None yet. Changes appear after a server's second daily check.
| string |
| city | string |
| near | object | Distance search on lists with coordinates: one of place, zip, lat+lng or points, with radius_miles. |
| metro | string | Only rows in one metro area (CBSA): its 5-digit code ("37980") or its name ("Philadelphia", "Philadelphia, PA"). The same as areas_in {"by": "metro", "ids": [code]}. |
| state | string |
| total | integer | Base rows wanted, first in answer order |
| where | array |
| county | string |
| relate * | object | Relate each base row to an anchor set. nearest: the k nearest anchors with miles. count_within: rank by anchors within radius_miles. within_any: rows with an anchor within radius_miles. none_within: rows with none. same_place / not_same_place: base rows that are (or are not) the same physical place … |
| dataset | string |
| exclude | array | Dataset slugs left out wherever the set expands: a category minus one of its members (a list's competitors are its own category with itself excluded). |
| areas_in | object | Only rows in these areas, e.g. {"by": "county", "ids": ["51760"]} for Richmond city, VA — the ids count_by_area returns, placed the same way (/find: areas_in=county:51760). |
| category | string |
| datasets | array |
| opendata | object | Instead of dataset / datasets / category: a public register read live from its publisher at question time (e.g. a state's licensed child-care programs). Matched by distance only (relate.mode near / not_near, near_m metres). Not a list we sell: the answer names the publisher, licence and read time, a… |
| area_where | array | Only rows whose county/zip/state/metro meets a Census condition, each as "<kind>:<attribute><op><value>" (ops > >= < <= =; values accept 1M, 250k, $50,000, 10%), e.g. "county:population>1000000". Every clause must hold; the fact is the area's, not the row's, and it adds nothing to the price. Attribu… |
| area_columns | array | Census, NOAA, FEMA and USDA facts added to every row as columns named <kind>_<attribute>, each as "<kind>:<attribute>,<attribute>", e.g. "county:population,median_household_income" — the county / ZIP / metro / state figures beside each location, in the preview and in the file you buy, after the area… |
{
"name": "relate_locations",
"title": "Relate two sets of locations (free)",
"description": "Free. How one set of places relates to another, by straight-line distance. The base set is the usual dataset / datasets / category plus filters; relate.anchor is the other set, given the same way. Modes: nearest (each base row's k<=3 nearest anchors with miles), count_within (rank base rows by how many anchors are within radius_miles), within_any (base rows with at least one anchor within radius_miles), none_within (base rows with no anchor within radius_miles). Mode next_best (no anchor, needs the base set's state) ranks the candidate new sites in that state by how well they match what the base list's own locations typically have nearby, blended with an estimated market capture; every candidate names its matched factors. Mode typically_near answers \"who is X typically located near?\" — the profile: the kinds of place and brands the base list's locations have nearby far more often than a typical spot (share of locations, lift, average miles), with an `answer` sentence and a link to the ranked sites; state optional (without one it is computed in the list's top state and the answer says which); a thin sample is said, never sold. Every set (base, anchor) also takes metro (a CBSA code or name) or areas_in (county / ZIP / metro / state ids), like count_locations. Mode near / not_near matches by distance only (near_m metres, default 30) and is how a LIVE public register is compared: give a set as opendata {source, state} instead of a dataset — search_datasets with kind \"register\" finds the source key. A register is read at the moment you ask, never sold; the answer names its publisher, licence and read time. Returns counts for both sets (rows without coordinates are left out and counted), summary stats, up to 3 preview rows, the price of the full answer (base rows plus the anchor rows named, each at its dataset's per-row rate, one card fee) and how to buy it with query_locations or create_query_checkout using the same arguments. Example: {\"dataset\": \"<slug>\", \"state\": \"VA\", \"relate\": {\"mode\": \"nearest\", \"k\": 1, \"anchor\": {\"dataset\": \"<other slug>\", \"metro\": \"Richmond\"}}}. Profile: {\"dataset\": \"<slug>\", \"relate\": {\"mode\": \"typically_near\"}}. Live register: {\"dataset\": \"ymca\", \"state\": \"NY\", \"relate\": {\"mode\": \"near\", \"near_m\": 30, \"anchor\": {\"opendata\": {\"source\": \"data.ny.gov/cb42-qumz\", \"state\": \"NY\"}}}}.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"relate"
],
"properties": {
"zip": {
"type": "string"
},
"city": {
"type": "string"
},
"near": {
"type": "object",
"properties": {
"lat": {
"type": "number"
},
"lng": {
"type": "number"
},
"zip": {
"type": "string",
"description": "5-digit zip"
},
"place": {
"type": "string",
"description": "City or town with state, e.g. \"Topeka, KS\""
},
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"lat": {
"$ref": "#/properties/near/properties/lat"
},
"lng": {
"$ref": "#/properties/near/properties/lng"
},
"zip": {
"$ref": "#/properties/near/properties/zip"
},
"place": {
"$ref": "#/properties/near/properties/place"
}
},
"additionalProperties": false
},
"maxItems": 10,
"minItems": 1,
"description": "Several points instead of one place/zip/lat+lng (at most 10): a row counts when it is within the radius of ANY of them, e.g. an operator's offices."
},
"radius_miles": {
"type": "number",
"maximum": 500,
"description": "Only rows within this straight-line distance of the point (or of any of the points). Free.",
"exclusiveMinimum": 0
}
},
"description": "Distance search on lists with coordinates: one of place, zip, lat+lng or points, with radius_miles.",
"additionalProperties": false
},
"metro": {
"type": "string",
"description": "Only rows in one metro area (CBSA): its 5-digit code (\"37980\") or its name (\"Philadelphia\", \"Philadelphia, PA\"). The same as areas_in {\"by\": \"metro\", \"ids\": [code]}."
},
"state": {
"type": "string"
},
"total": {
"type": "integer",
"maximum": 10000,
"minimum": 1,
"description": "Base rows wanted, first in answer order"
},
"where": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"op"
],
"properties": {
"op": {
"enum": [
"eq",
"ne",
"gt",
"gte",
"lt",
"lte",
"in",
"contains",
"starts_with",
"is_blank",
"not_blank",
"not_contains",
"not_in",
"any_of"
],
"type": "string"
},
"field": {
"type": "string"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "array",
"items": {
"type": [
"string",
"number"
]
}
}
]
},
"any_of": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"op"
],
"properties": {
"op": {
"enum": [
"eq",
"ne",
"gt",
"gte",
"lt",
"lte",
"in",
"contains",
"starts_with",
"is_blank",
"not_blank",
"not_contains",
"not_in",
"any_of"
],
"type": "string"
},
"field": {
"type": "string"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "array",
"items": {
"type": [
"string",
"number"
]
}
}
]
}
},
"additionalProperties": false
},
"maxItems": 12
}
},
"additionalProperties": false
},
"maxItems": 12
},
"county": {
"type": "string"
},
"relate": {
"type": "object",
"required": [
"mode"
],
"properties": {
"k": {
"type": "integer",
"maximum": 3,
"minimum": 1,
"description": "nearest: how many anchors per base row. next_best / typically_near: H3 rings counted as nearby, 1-3 (default 2, about a mile)"
},
"also": {
"type": "array",
"items": {
"type": "string"
},
"description": "same_place / near only: the sets a base row must be the same place as (near: within near_m of) some row of, by label (\"b\", \"c\"); default every set"
},
"mode": {
"enum": [
"nearest",
"count_within",
"within_any",
"none_within",
"same_place",
"not_same_place",
"near",
"not_near",
"next_best",
"typically_near",
"overlap"
],
"type": "string",
"description": "nearest | count_within | within_any | none_within | same_place | not_same_place | near | not_near | next_best | typically_near | overlap"
},
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "next_best only: candidates ranked (default 50)"
},
"order": {
"enum": [
"asc",
"desc"
],
"type": "string"
},
"anchor": {
"type": "object",
"properties": {
"zip": {
"$ref": "#/properties/zip"
},
"city": {
"$ref": "#/properties/city"
},
"near": {
"$ref": "#/properties/near"
},
"metro": {
"$ref": "#/properties/metro"
},
"state": {
"$ref": "#/properties/state"
},
"where": {
"$ref": "#/properties/where"
},
"county": {
"$ref": "#/properties/county"
},
"dataset": {
"$ref": "#/properties/dataset"
},
"exclude": {
"$ref": "#/properties/exclude"
},
"areas_in": {
"$ref": "#/properties/areas_in"
},
"category": {
"$ref": "#/properties/category"
},
"datasets": {
"$ref": "#/properties/datasets"
},
"opendata": {
"$ref": "#/properties/opendata",
"description": "Instead of dataset / datasets / category: a public register read live from its publisher at question time (e.g. a state's licensed child-care programs). Matched by distance only (relate.mode near / not_near, near_m metres). Not a list we sell: the answer names the publisher, licence and read time, and prices only the rows of our lists."
},
"area_where": {
"$ref": "#/properties/area_where"
},
"area_columns": {
"$ref": "#/properties/area_columns"
}
},
"description": "The other set: dataset, datasets or category, plus filters. Every mode but next_best and typically_near needs it",
"additionalProperties": false
},
"lambda": {
"type": "number",
"maximum": 10,
"description": "next_best only: the Huff distance-decay exponent (default 2, the traditional value)",
"exclusiveMinimum": 0
},
"near_m": {
"type": "integer",
"maximum": 200,
"minimum": 10,
"description": "near / not_near only: how close, in metres, a place of the other set must be (default 30, 10-200). Distance only — no name or address is compared. /find: near_m=30."
},
"anchors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"zip": {
"$ref": "#/properties/zip"
},
"city": {
"$ref": "#/properties/city"
},
"near": {
"$ref": "#/properties/near"
},
"metro": {
"$ref": "#/properties/metro"
},
"state": {
"$ref": "#/properties/state"
},
"where": {
"$ref": "#/properties/where"
},
"county": {
"$ref": "#/properties/county"
},
"dataset": {
"$ref": "#/properties/dataset"
},
"exclude": {
"$ref": "#/properties/exclude"
},
"areas_in": {
"$ref": "#/properties/areas_in"
},
"category": {
"$ref": "#/properties/category"
},
"datasets": {
"$ref": "#/properties/datasets"
},
"opendata": {
"$ref": "#/properties/opendata",
"description": "Instead of dataset / datasets / category: a public register read live from its publisher at question time (e.g. a state's licensed child-care programs). Matched by distance only (relate.mode near / not_near, near_m metres). Not a list we sell: the answer names the publisher, licence and read time, and prices only the rows of our lists."
},
"area_where": {
"$ref": "#/properties/area_where"
},
"area_columns": {
"$ref": "#/properties/area_columns"
}
},
"additionalProperties": false
},
"maxItems": 2,
"description": "same_place (and near) only: further sets (c, d) after anchor (b), each given the same way"
},
"not_also": {
"type": "array",
"items": {
"type": "string"
},
"description": "same_place / near only: the sets a base row must not match any row of; not_same_place (not_near) with one set is [\"b\"]"
},
"anchor_all": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "string"
}
},
"maxItems": 3,
"minItems": 2,
"description": "count_within / within_any: one of each instead of one of any. The anchor set's dataset slugs grouped as the question named them — [[\"a\"],[\"b\"]] keeps only base rows with a row of both within the distance. Omit for the ordinary any-of reading."
},
"radius_miles": {
"type": "number",
"maximum": 250,
"exclusiveMinimum": 0
},
"reveal_anchor": {
"type": "boolean"
}
},
"description": "Relate each base row to an anchor set. nearest: the k nearest anchors with miles. count_within: rank by anchors within radius_miles. within_any: rows with an anchor within radius_miles. none_within: rows with none. same_place / not_same_place: base rows that are (or are not) the same physical place as a row of each set (same address, or within 60 m sharing a name word); N-way with anchors, also and not_also. near / not_near: the same N-way shape matched by distance only, within near_m metres (default 30); the rule for a live register given as a set's opendata. next_best: no anchor; needs the base set's state: candidate sites in that state ranked by how well they match what the base list's locations typically have nearby, blended with estimated market capture. typically_near: the profile behind next_best, no anchor, state optional: what the base list's locations typically have nearby (each kind of place or brand near at least 15% of them and 1.5x as often as near a typical commercial spot); under 10 locations the pattern carries a thin-sample note and nothing is sold. overlap: a territory question: every base and anchor row buffered by radius_miles (default 3, 1-25), each set unioned into one shape, answered as the share of the base's shape the anchor's covers plus each base row's own share (lowest first is the whitespace). Free: the shares and square miles. Paid: the base rows with their share, at the list's per-row rate.",
"additionalProperties": false
},
"dataset": {
"type": "string"
},
"exclude": {
"type": "array",
"items": {
"type": "string"
},
"description": "Dataset slugs left out wherever the set expands: a category minus one of its members (a list's competitors are its own category with itself excluded)."
},
"areas_in": {
"type": "object",
"required": [
"by",
"ids"
],
"properties": {
"by": {
"enum": [
"county",
"zip",
"state",
"metro"
],
"type": "string"
},
"ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 200,
"minItems": 1,
"description": "County FIPS, 5-digit ZIP, CBSA code or state code — the `id` of a count_by_area row"
}
},
"description": "Only rows in these areas, e.g. {\"by\": \"county\", \"ids\": [\"51760\"]} for Richmond city, VA — the ids count_by_area returns, placed the same way (/find: areas_in=county:51760).",
"additionalProperties": false
},
"category": {
"type": "string"
},
"datasets": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
},
"opendata": {
"type": "object",
"required": [
"source"
],
"properties": {
"zips": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Or cut it to 5-digit ZIP codes, e.g. [\"78114\", \"78154\"] (/find: opendata_zips=78114,78154)"
},
"state": {
"type": "string",
"description": "Cut the register to one state, e.g. \"NY\" (/find: opendata_state=NY)"
},
"where": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 12,
"description": "Conditions on the register's own columns, each \"column:op:value\" with op eq | starts_with | contains | not_blank, e.g. [\"license_status:starts_with:Active\"] (/find: opendata_where=)"
},
"source": {
"type": "string",
"description": "The register's key, \"<domain>/<id>\" — search_datasets with kind \"register\" finds it, e.g. \"data.ny.gov/cb42-qumz\" (New York's licensed child-care programs)"
}
},
"description": "Instead of dataset / datasets / category: a public register read live from its publisher at question time (e.g. a state's licensed child-care programs). Matched by distance only (relate.mode near / not_near, near_m metres). Not a list we sell: the answer names the publisher, licence and read time, and prices only the rows of our lists.",
"additionalProperties": false
},
"area_where": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 6,
"description": "Only rows whose county/zip/state/metro meets a Census condition, each as \"<kind>:<attribute><op><value>\" (ops > >= < <= =; values accept 1M, 250k, $50,000, 10%), e.g. \"county:population>1000000\". Every clause must hold; the fact is the area's, not the row's, and it adds nothing to the price. Attributes: e.g. population, households, median_household_income, median_age, pct_65_plus, housing_units; Census ACS people, income, education and housing; businesses and jobs by NAICS sector (<sector>_establishments, <sector>_employees) or detailed code (naics_<code>_establishments / _employees / _payroll); population growth; NOAA climate normals and actuals; NOAA storm events; station weather normals; hourly weather normals; building stock; Zillow home values; Zillow rents; building permits; IRS tax returns; FEMA hazard risk; USDA farm census. Every key (11,012) with its label, unit and kinds: see /area-attributes.json."
},
"area_columns": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 6,
"description": "Census, NOAA, FEMA and USDA facts added to every row as columns named <kind>_<attribute>, each as \"<kind>:<attribute>,<attribute>\", e.g. \"county:population,median_household_income\" — the county / ZIP / metro / state figures beside each location, in the preview and in the file you buy, after the area's id and name (county_fips, county_name; zip_code; metro_cbsa, metro_name; state_code, state_name). Free. The same attribute words area_where takes (listed there)."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}| Parameter | Type | Description |
|---|---|---|
| by * | string | one of ["county","zip","state","metro"] |
| all | boolean | List every matching area, however many |
| has | array | |
| per | number | Counts per this many residents of each area from its Census population (100000 adds per_100k to every area and ranks by it), or per this many of per_field. |
| sets * | array | |
| lacks | array | |
| limit | integer | Areas listed per call (default: every matching area when 500 or fewer match, else the first 100; at most 1000) |
| offset | integer | Areas to skip before the first listed: page through every matching area with limit + offset. The answer's page block gives total and the next offset (null on the last page). |
| in_state | string | Only areas in this state |
| order_by | object | Rank the areas: {"field": "median_household_income"} for the richest counties first, {"field": "a", "direction": "asc"} for the fewest of set a first. Unknown figures sort last. |
| per_field | string | With per: the Census count the rate is over instead of population, e.g. per=1000 with per_field=construction_establishments adds per_1000_construction_establishments. Any count attribute: population, households, housing_units, establishments, employees, agriculture_establishments, mining_establishme… |
| area_where | array | Only areas meeting a Census condition, each as "<kind>:<attribute><op><value>" about the same kind as by (or a state), e.g. "county:population>500000" with lacks for "counties over 500k people with no X". Attributes: e.g. population, households, median_household_income, median_age, pct_65_plus, hous… |
| top_values | object | The most common values of one class column per area, per set (top on each area row): what kinds of place make up a count — {"column": "category"} shows that Elkhart County's 47 trailer dealers are 30 dealers, 12 manufacturers, 5 horse-trailer specialists. Free, bounded, and the same figures a filter… |
| with_sample | boolean | Free. On the first 10 areas listed, each set's fixed published sample rows that fall inside the area (source_dataset, the list's columns, matches_your_question). The same published rows every question sees, so cells never add up to the file. |
| area_columns | array | Census, NOAA, FEMA and USDA figures RETURNED on every area row (in attributes), each as "<kind>:<attribute>,<attribute>" about the same kind as by (or "state:…" for the area's state, returned as state_<attribute>), e.g. ["county:population,median_household_income,households"]. Free. The vocabulary i… |
{
"name": "count_by_area",
"title": "Count locations by area (free)",
"description": "Free, counts only. Counts places per county / zip / state / metro for 1 to 4 labeled sets (each a dataset, datasets or category plus filters), and compares them: has (areas with at least one of every listed set) and lacks (areas with none of any listed set). E.g. counties that have set a but no set b; ZIPs where a closure-filtered set exists and another set still has places. Rows that cannot be placed are counted, never read as zero. Every area row can carry Census / NOAA figures (area_columns) and the areas can be ranked by one of them or by a count (order_by), so markets rank by demand; limit + offset page through every matching area (page.total, page.nextOffset), or all: true lists every matching area in one answer; top_values shows what kinds of place make up each count. Warnings lead the answer when they change how it reads: a set that could not be counted is never a zero (no has/lacks answer uses it), a lacks set too thin to support absence (few places, or an open-data brand list below the brand's own count), and areas in states a set's lists do not cover (those rows carry notCovered: there 0 means not covered, not none there). notes explain placement (duplicates counted once, state column vs county). Reach: a set's `near` (the same shape count_locations takes) keeps only its rows within radius_miles of one point or of any of several `points`, before they are rolled up by area — so a regional operator is counted where it reaches, not nationally: \"metros within 100 miles of these three offices\" is by=metro with near={points:[…], radius_miles:100}. Drive time is not offered. FROM A CELL TO ITS ROWS: every area listed carries `rows` per set: the count, the price of those rows, a link, and `args` — the count_locations / query_locations / create_query_checkout call (the set's filters plus areas_in for that area) that returns exactly them, so a count cell is one call from its named rows. with_sample: true adds, on the first areas listed, the free preview behind each cell — the list's fixed published sample rows that fall inside the area, marked matches_your_question (never a sample of the area's places). Example: {\"by\": \"county\", \"sets\": [{\"label\": \"a\", \"dataset\": \"<slug>\"}, {\"label\": \"b\", \"dataset\": \"<other slug>\"}], \"has\": [\"a\"], \"lacks\": [\"b\"], \"in_state\": \"VA\"}. Ranked by demand: {\"by\": \"county\", \"sets\": [{\"label\": \"a\", \"dataset\": \"<slug>\"}], \"area_columns\": [\"county:population,median_household_income\"], \"order_by\": {\"field\": \"population\"}, \"limit\": 100, \"offset\": 100}. Regional: {\"by\": \"metro\", \"sets\": [{\"label\": \"ours\", \"dataset\": \"<slug>\", \"near\": {\"points\": [{\"place\": \"Richmond, VA\"}, {\"place\": \"Norfolk, VA\"}], \"radius_miles\": 100}}]}.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"by",
"sets"
],
"properties": {
"by": {
"enum": [
"county",
"zip",
"state",
"metro"
],
"type": "string"
},
"all": {
"type": "boolean",
"description": "List every matching area, however many"
},
"has": {
"type": "array",
"items": {
"type": "string"
}
},
"per": {
"type": "number",
"minimum": 1,
"description": "Counts per this many residents of each area from its Census population (100000 adds per_100k to every area and ranks by it), or per this many of per_field."
},
"sets": {
"type": "array",
"items": {
"type": "object",
"required": [
"label"
],
"properties": {
"zip": {
"type": "string"
},
"city": {
"type": "string"
},
"near": {
"type": "object",
"properties": {
"lat": {
"type": "number"
},
"lng": {
"type": "number"
},
"zip": {
"type": "string",
"description": "5-digit zip"
},
"place": {
"type": "string",
"description": "City or town with state, e.g. \"Topeka, KS\""
},
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"lat": {
"$ref": "#/properties/sets/items/properties/near/properties/lat"
},
"lng": {
"$ref": "#/properties/sets/items/properties/near/properties/lng"
},
"zip": {
"$ref": "#/properties/sets/items/properties/near/properties/zip"
},
"place": {
"$ref": "#/properties/sets/items/properties/near/properties/place"
}
},
"additionalProperties": false
},
"maxItems": 10,
"minItems": 1,
"description": "Several points instead of one place/zip/lat+lng (at most 10): a row counts when it is within the radius of ANY of them, e.g. an operator's offices."
},
"radius_miles": {
"type": "number",
"maximum": 500,
"description": "Only rows within this straight-line distance of the point (or of any of the points). Free.",
"exclusiveMinimum": 0
}
},
"description": "Distance search on lists with coordinates: one of place, zip, lat+lng or points, with radius_miles.",
"additionalProperties": false
},
"label": {
"type": "string",
"description": "Short name, e.g. \"a\" or \"closed\""
},
"metro": {
"type": "string",
"description": "Only rows in one metro area (CBSA): its 5-digit code (\"37980\") or its name (\"Philadelphia\", \"Philadelphia, PA\"). The same as areas_in {\"by\": \"metro\", \"ids\": [code]}."
},
"state": {
"type": "string"
},
"where": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"op"
],
"properties": {
"op": {
"enum": [
"eq",
"ne",
"gt",
"gte",
"lt",
"lte",
"in",
"contains",
"starts_with",
"is_blank",
"not_blank",
"not_contains",
"not_in",
"any_of"
],
"type": "string"
},
"field": {
"type": "string"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "array",
"items": {
"type": [
"string",
"number"
]
}
}
]
},
"any_of": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"op"
],
"properties": {
"op": {
"enum": [
"eq",
"ne",
"gt",
"gte",
"lt",
"lte",
"in",
"contains",
"starts_with",
"is_blank",
"not_blank",
"not_contains",
"not_in",
"any_of"
],
"type": "string"
},
"field": {
"type": "string"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "array",
"items": {
"type": [
"string",
"number"
]
}
}
]
}
},
"additionalProperties": false
},
"maxItems": 12
}
},
"additionalProperties": false
},
"maxItems": 12
},
"county": {
"type": "string"
},
"dataset": {
"type": "string"
},
"exclude": {
"type": "array",
"items": {
"type": "string"
},
"description": "Dataset slugs left out wherever the set expands: a category minus one of its members (a list's competitors are its own category with itself excluded)."
},
"areas_in": {
"type": "object",
"required": [
"by",
"ids"
],
"properties": {
"by": {
"enum": [
"county",
"zip",
"state",
"metro"
],
"type": "string"
},
"ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 200,
"minItems": 1,
"description": "County FIPS, 5-digit ZIP, CBSA code or state code — the `id` of a count_by_area row"
}
},
"description": "Only rows in these areas, e.g. {\"by\": \"county\", \"ids\": [\"51760\"]} for Richmond city, VA — the ids count_by_area returns, placed the same way (/find: areas_in=county:51760).",
"additionalProperties": false
},
"category": {
"type": "string"
},
"datasets": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
},
"opendata": {
"type": "object",
"required": [
"source"
],
"properties": {
"zips": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Or cut it to 5-digit ZIP codes, e.g. [\"78114\", \"78154\"] (/find: opendata_zips=78114,78154)"
},
"state": {
"type": "string",
"description": "Cut the register to one state, e.g. \"NY\" (/find: opendata_state=NY)"
},
"where": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 12,
"description": "Conditions on the register's own columns, each \"column:op:value\" with op eq | starts_with | contains | not_blank, e.g. [\"license_status:starts_with:Active\"] (/find: opendata_where=)"
},
"source": {
"type": "string",
"description": "The register's key, \"<domain>/<id>\" — search_datasets with kind \"register\" finds it, e.g. \"data.ny.gov/cb42-qumz\" (New York's licensed child-care programs)"
}
},
"description": "Instead of dataset / datasets / category: a public register read live from its publisher at question time (e.g. a state's licensed child-care programs). Matched by distance only (relate.mode near / not_near, near_m metres). Not a list we sell: the answer names the publisher, licence and read time, and prices only the rows of our lists.",
"additionalProperties": false
},
"area_where": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 6,
"description": "Only rows whose county/zip/state/metro meets a Census condition, each as \"<kind>:<attribute><op><value>\" (ops > >= < <= =; values accept 1M, 250k, $50,000, 10%), e.g. \"county:population>1000000\". Every clause must hold; the fact is the area's, not the row's, and it adds nothing to the price. Attributes: e.g. population, households, median_household_income, median_age, pct_65_plus, housing_units; Census ACS people, income, education and housing; businesses and jobs by NAICS sector (<sector>_establishments, <sector>_employees) or detailed code (naics_<code>_establishments / _employees / _payroll); population growth; NOAA climate normals and actuals; NOAA storm events; station weather normals; hourly weather normals; building stock; Zillow home values; Zillow rents; building permits; IRS tax returns; FEMA hazard risk; USDA farm census. Every key (11,012) with its label, unit and kinds: see /area-attributes.json."
},
"area_columns": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 6,
"description": "Census, NOAA, FEMA and USDA facts added to every row as columns named <kind>_<attribute>, each as \"<kind>:<attribute>,<attribute>\", e.g. \"county:population,median_household_income\" — the county / ZIP / metro / state figures beside each location, in the preview and in the file you buy, after the area's id and name (county_fips, county_name; zip_code; metro_cbsa, metro_name; state_code, state_name). Free. The same attribute words area_where takes (listed there)."
}
},
"additionalProperties": false
},
"maxItems": 4,
"minItems": 1
},
"lacks": {
"type": "array",
"items": {
"type": "string"
}
},
"limit": {
"type": "integer",
"maximum": 1000,
"minimum": 1,
"description": "Areas listed per call (default: every matching area when 500 or fewer match, else the first 100; at most 1000)"
},
"offset": {
"type": "integer",
"maximum": 100000,
"minimum": 0,
"description": "Areas to skip before the first listed: page through every matching area with limit + offset. The answer's page block gives total and the next offset (null on the last page)."
},
"in_state": {
"type": "string",
"description": "Only areas in this state"
},
"order_by": {
"type": "object",
"required": [
"field"
],
"properties": {
"field": {
"type": "string",
"description": "count (default), a set label, per (with per), name, or an attribute the rows carry from area_where / per_field / area_columns"
},
"direction": {
"enum": [
"asc",
"desc"
],
"type": "string",
"description": "Default desc (name: asc)"
}
},
"description": "Rank the areas: {\"field\": \"median_household_income\"} for the richest counties first, {\"field\": \"a\", \"direction\": \"asc\"} for the fewest of set a first. Unknown figures sort last.",
"additionalProperties": false
},
"per_field": {
"type": "string",
"description": "With per: the Census count the rate is over instead of population, e.g. per=1000 with per_field=construction_establishments adds per_1000_construction_establishments. Any count attribute: population, households, housing_units, establishments, employees, agriculture_establishments, mining_establishments, utilities_establishments, every <sector>_establishments / <sector>_employees, and every naics_<code>_establishments / naics_<code>_employees (2- to 6-digit NAICS, e.g. naics_8111_establishments)."
},
"area_where": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 6,
"description": "Only areas meeting a Census condition, each as \"<kind>:<attribute><op><value>\" about the same kind as by (or a state), e.g. \"county:population>500000\" with lacks for \"counties over 500k people with no X\". Attributes: e.g. population, households, median_household_income, median_age, pct_65_plus, housing_units; Census ACS people, income, education and housing; businesses and jobs by NAICS sector (<sector>_establishments, <sector>_employees) or detailed code (naics_<code>_establishments / _employees / _payroll); population growth; NOAA climate normals and actuals; NOAA storm events; station weather normals; hourly weather normals; building stock; Zillow home values; Zillow rents; building permits; IRS tax returns; FEMA hazard risk; USDA farm census. Every key (11,012) with its label, unit and kinds: see /area-attributes.json."
},
"top_values": {
"type": "object",
"required": [
"column"
],
"properties": {
"n": {
"type": "integer",
"maximum": 5,
"minimum": 1,
"description": "Values per area, 1-5 (default 3)"
},
"column": {
"type": "string",
"description": "A CLASS column of the sets' files: category, type, brand, tier, status… (get_dataset lists columns)"
}
},
"description": "The most common values of one class column per area, per set (top on each area row): what kinds of place make up a count — {\"column\": \"category\"} shows that Elkhart County's 47 trailer dealers are 30 dealers, 12 manufacturers, 5 horse-trailer specialists. Free, bounded, and the same figures a filtered count gives. A name, address or contact column is refused: a free answer names classes, never records — the rows are in the file you buy.",
"additionalProperties": false
},
"with_sample": {
"type": "boolean",
"description": "Free. On the first 10 areas listed, each set's fixed published sample rows that fall inside the area (source_dataset, the list's columns, matches_your_question). The same published rows every question sees, so cells never add up to the file."
},
"area_columns": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 40,
"description": "Census, NOAA, FEMA and USDA figures RETURNED on every area row (in attributes), each as \"<kind>:<attribute>,<attribute>\" about the same kind as by (or \"state:…\" for the area's state, returned as state_<attribute>), e.g. [\"county:population,median_household_income,households\"]. Free. The vocabulary is the area manifest — the same words area_where takes (population, households, median household income, median age, growth since 2020, home values, <sector>_establishments / <sector>_employees by NAICS sector, and the NOAA weather elements); https://locationlists.com/find?areas=county&dataset=<slug>&area_columns=county:<attribute> refuses an unknown attribute by name and lists the nearest ones. Rank the areas by one with order_by."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}| Parameter | Type | Description |
|---|---|---|
| zip | string | Shortcut for where zip eq <value> |
| city | string | Shortcut for where city eq <value> |
| near | object | Distance search on lists with map coordinates (distanceSearch in search results): one of place, zip, lat+lng or `points` (within reach of any of them). Rows come back nearest first with a distance_miles column (straight line; no drive time); limit for 'the 10 closest', radius_miles for 'everything w… |
| limit | integer | Price a slice instead of every match: the first `limit` rows past `offset` in the delivery order — e.g. near a place with limit 10 for the 10 nearest — exactly the rows a purchase with the same limit returns. The answer's `slice` has their exact price, each row source at its own rate (open-data rows… |
| metro | string | Only rows in one metro area (CBSA): its 5-digit code ("37980") or its name ("Philadelphia", "Philadelphia, PA"). The same as areas_in {"by": "metro", "ids": [code]}: rows are placed the way count_by_area places them, so "all hospitals in the Philadelphia metro" is one count, one price and one purcha… |
| state | string | Shortcut for where state eq <value>. Two-letter code; several states comma-separated ("VA,NC,SC") are one `in`. |
| total | integer | With datasets or category: rows wanted across all of them, split in proportion to each dataset's matches |
| where | array | Conditions on any column, all of which must hold. Blank cells never satisfy a comparison (the answer counts rows excluded only for that, and a small answer says what each condition removed). |
| county | string | Shortcut for where county eq <value> |
| offset | integer | With limit: skip this many matching rows, as a paged purchase does, so the quote is for that page |
| dataset | string | Dataset slug, e.g. nonprofits-va. To combine several, give datasets or category instead. |
| exclude | array | With category or datasets: dataset slugs left out (a category minus one of its members, e.g. a list's competitors are its own category with itself excluded) |
| permits | object | Only rows with a building permit nearby, read live from the city's own permit register at question time — e.g. {"dataset": "<slug>", "city": "Austin", "state": "TX", "permits": {"days": 90, "type": "commercial", "min_usd": 1000000}}. One city register per question (from the base set's city, a ZIP in… |
| areas_in | object | Only rows in these areas, e.g. {"by": "county", "ids": ["18039"]} for Elkhart County, IN — the ids count_by_area returns. Rows are placed by county_fips, county + state, coordinates or ZIP, the same as count_by_area. |
| category | string | Instead of dataset: every dataset of one kind — "retail" (store chains), an industry or subcategory, or a kind of business such as "restaurant" or "bank branch" (search_datasets names these) |
| datasets | array | Instead of dataset: several dataset slugs answered as one (one count, one preview, one price, one file) |
| order_by | object | With limit: the order the slice is taken in, as a purchase takes it. Without it, nearest first with `near`, else file order. |
| area_where | array | Only rows whose county/zip/state/metro meets a Census condition, each as "<kind>:<attribute><op><value>" (ops > >= < <= =; values accept 1M, 250k, $50,000, 10%), e.g. "county:population>1000000". Every clause must hold; the fact is the area's, not the row's, and it adds nothing to the price. Attribu… |
| area_columns | array | Census, NOAA, FEMA and USDA facts added to every row as columns named <kind>_<attribute>, each as "<kind>:<attribute>,<attribute>", e.g. "county:population,median_household_income" — the county / ZIP / metro / state figures beside each location, in the preview and in the file you buy, after the area… |
{
"name": "count_locations",
"title": "Count matching locations (free)",
"description": "Free. How many rows of one dataset match a filter — on geography and any other column (e.g. nonprofits with revenue_amt gt 2000000, dealers with dealerClass eq 'Elite'). Also reports how many rows were excluded only because a tested column was blank, so a thin column is not mistaken for a small answer; a small or empty answer says how many rows each condition removed and what the column really holds. Returns the exact card price of the matching rows, a link where the user can see and buy them, and the same rows in a cheaper list when one has them. Works for geography: city, state, county, zip, metro (a CBSA code or name: \"all hospitals in the Philadelphia metro\" is one call), areas_in (the county / ZIP / metro / state ids count_by_area returns), or `near` a place (\"Los Angeles, CA\"), zip or lat/lng within radius_miles, on lists with coordinates. AREA DATA, free: area_where keeps rows whose county / ZIP / metro / state meets a condition on a Census, weather, housing-market or tax-return figure (county:population>1000000, zip:typical_home_value>500000, zip:share_income_200k_plus>20), and area_columns adds those figures to every row as columns (county:population,median_household_income,typical_rent,average_adjusted_gross_income). COVERAGE: a list's coverage is measured on its rows (get_dataset coverageDetail: states and rows per state); a state the list has no rows in is said as not covered, never as none there. get_sample takes the same filters and returns the count plus the list's fixed free sample rows, marked matches_your_question. The result's `next` says exactly how to get every matching row. To cover several chains near one place, pass datasets or category (e.g. \"retail\" or \"restaurant\") and a total instead of dataset: one answer with counts per dataset, duplicates removed and up to 3 preview rows, one price and one file. Use get_dataset first for the column names. Scans the live file, so it can take several seconds on large datasets. Every number in the result is named: matched (rows meeting every filter), rowsRead (how many rows of the list were read to answer: the whole file for one of our lists, or, for an Overture list, only the index shards the question's area or place touches — so it can be far smaller than the list), maxRowsPerCall (the most rows one paid call returns), excludedBlank (rows dropped only because a tested column was blank), and price (soldBy says whether the list is sold as a file, by the row, or both; perRowUsd and perCallFeeUsd are the by-the-row terms, wallet the total a self-paying agent pays, breakdown each row source at its rate). To price exactly what one query_locations call returns — \"the 10 nearest\" — pass the same limit (and offset / order_by): `slice` then has that call's exact amount line by line and the card price of the same rows. A paid call is billed for the rows it returns: each row at its own list's per-row rate (an Overture open-data row at $0.005; a row of a chain LocationLists sells its own list for, at that list's rate), plus a $0.01 per-call fee, rounded once to the nearest cent, at least $0.02, never more than the whole list. count_locations with the same filters, limit and offset quotes exactly that page, row source by row source (price.breakdown), before anything is paid.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"zip": {
"type": "string",
"description": "Shortcut for where zip eq <value>"
},
"city": {
"type": "string",
"description": "Shortcut for where city eq <value>"
},
"near": {
"type": "object",
"properties": {
"lat": {
"type": "number"
},
"lng": {
"type": "number"
},
"zip": {
"type": "string",
"description": "5-digit zip"
},
"place": {
"type": "string",
"description": "City or town with state, e.g. \"Topeka, KS\" (a neighborhood or misspelling falls back to the nearest Census place name, and the answer says which)."
},
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"lat": {
"$ref": "#/properties/near/properties/lat"
},
"lng": {
"$ref": "#/properties/near/properties/lng"
},
"zip": {
"$ref": "#/properties/near/properties/zip"
},
"place": {
"type": "string",
"description": "City or town with state, e.g. \"Topeka, KS\""
}
},
"additionalProperties": false
},
"maxItems": 10,
"minItems": 1,
"description": "Several points instead of one place/zip/lat+lng (at most 10): a row counts when it is within the radius of ANY of them, e.g. an operator's offices."
},
"radius_miles": {
"type": "number",
"maximum": 500,
"description": "Only rows within this straight-line distance of the point (or of any of the points). Free.",
"exclusiveMinimum": 0
}
},
"description": "Distance search on lists with map coordinates (distanceSearch in search results): one of place, zip, lat+lng or `points` (within reach of any of them). Rows come back nearest first with a distance_miles column (straight line; no drive time); limit for 'the 10 closest', radius_miles for 'everything within 25 miles'. Rows without coordinates are excluded and counted.",
"additionalProperties": false
},
"limit": {
"type": "integer",
"maximum": 10000,
"minimum": 1,
"description": "Price a slice instead of every match: the first `limit` rows past `offset` in the delivery order — e.g. near a place with limit 10 for the 10 nearest — exactly the rows a purchase with the same limit returns. The answer's `slice` has their exact price, each row source at its own rate (open-data rows vs rows of lists we sell), and the card price."
},
"metro": {
"type": "string",
"description": "Only rows in one metro area (CBSA): its 5-digit code (\"37980\") or its name (\"Philadelphia\", \"Philadelphia, PA\"). The same as areas_in {\"by\": \"metro\", \"ids\": [code]}: rows are placed the way count_by_area places them, so \"all hospitals in the Philadelphia metro\" is one count, one price and one purchase."
},
"state": {
"type": "string",
"description": "Shortcut for where state eq <value>. Two-letter code; several states comma-separated (\"VA,NC,SC\") are one `in`."
},
"total": {
"type": "integer",
"maximum": 10000,
"minimum": 1,
"description": "With datasets or category: rows wanted across all of them, split in proportion to each dataset's matches"
},
"where": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"op"
],
"properties": {
"op": {
"enum": [
"eq",
"ne",
"gt",
"gte",
"lt",
"lte",
"in",
"contains",
"starts_with",
"is_blank",
"not_blank",
"not_contains",
"not_in",
"any_of"
],
"type": "string",
"description": "eq/ne: case-insensitive (numeric when both sides are numbers; yes/true/y/1 are one answer). gt/gte/lt/lte: numeric, else text order (ISO dates work). in/not_in: value is an array. contains/not_contains/starts_with: text. is_blank/not_blank: no value (N/A, <UNAVAIL> count as blank). any_of: no value; kept when any condition in any_of holds."
},
"field": {
"type": "string",
"description": "Column name as listed by get_dataset (columns[].name), e.g. revenue_amt"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "array",
"items": {
"type": [
"string",
"number"
]
}
}
]
},
"any_of": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"op"
],
"properties": {
"op": {
"enum": [
"eq",
"ne",
"gt",
"gte",
"lt",
"lte",
"in",
"contains",
"starts_with",
"is_blank",
"not_blank",
"not_contains",
"not_in",
"any_of"
],
"type": "string"
},
"field": {
"type": "string"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "array",
"items": {
"type": [
"string",
"number"
]
}
}
]
}
},
"additionalProperties": false
},
"maxItems": 12,
"description": "With op any_of: the conditions, any one of which keeps the row."
}
},
"additionalProperties": false
},
"maxItems": 12,
"description": "Conditions on any column, all of which must hold. Blank cells never satisfy a comparison (the answer counts rows excluded only for that, and a small answer says what each condition removed)."
},
"county": {
"type": "string",
"description": "Shortcut for where county eq <value>"
},
"offset": {
"type": "integer",
"maximum": 10000,
"minimum": 0,
"description": "With limit: skip this many matching rows, as a paged purchase does, so the quote is for that page"
},
"dataset": {
"type": "string",
"description": "Dataset slug, e.g. nonprofits-va. To combine several, give datasets or category instead."
},
"exclude": {
"type": "array",
"items": {
"type": "string"
},
"description": "With category or datasets: dataset slugs left out (a category minus one of its members, e.g. a list's competitors are its own category with itself excluded)"
},
"permits": {
"type": "object",
"properties": {
"days": {
"type": "integer",
"maximum": 3650,
"minimum": 1,
"description": "Issued in the last N days (default 365)"
},
"type": {
"enum": [
"any",
"new_construction",
"commercial",
"residential",
"renovation",
"demolition",
"electrical",
"plumbing",
"mechanical",
"roofing",
"solar",
"sign",
"pool"
],
"type": "string",
"description": "The kind of permit (default any)"
},
"metres": {
"type": "integer",
"maximum": 200,
"minimum": 10,
"description": "How close a permit must be to the row, in metres (default 60)"
},
"min_usd": {
"type": "number",
"minimum": 0,
"description": "Valuation at least this many dollars"
}
},
"description": "Only rows with a building permit nearby, read live from the city's own permit register at question time — e.g. {\"dataset\": \"<slug>\", \"city\": \"Austin\", \"state\": \"TX\", \"permits\": {\"days\": 90, \"type\": \"commercial\", \"min_usd\": 1000000}}. One city register per question (from the base set's city, a ZIP in it, its county, or a state with one register); the cities read now: New York, NY; Los Angeles, CA; Chicago, IL; Dallas, TX; Austin, TX; San Francisco, CA; Seattle, WA; Nashville, TN. A kind or amount a register cannot tell is refused in words, never answered as any. Free: counts, a preview, the price of the matching rows; the openData block names the register, its publisher, licence and when it was read. On /find: &permits=1&permits_days=90&permits_type=commercial&permits_min_usd=1000000. Not sold through a checkout yet: the answer's link is the page.",
"additionalProperties": false
},
"areas_in": {
"type": "object",
"required": [
"by",
"ids"
],
"properties": {
"by": {
"enum": [
"county",
"zip",
"state",
"metro"
],
"type": "string"
},
"ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 200,
"minItems": 1,
"description": "County FIPS, 5-digit ZIP, CBSA code or state code — the `id` of a count_by_area row"
}
},
"description": "Only rows in these areas, e.g. {\"by\": \"county\", \"ids\": [\"18039\"]} for Elkhart County, IN — the ids count_by_area returns. Rows are placed by county_fips, county + state, coordinates or ZIP, the same as count_by_area.",
"additionalProperties": false
},
"category": {
"type": "string",
"description": "Instead of dataset: every dataset of one kind — \"retail\" (store chains), an industry or subcategory, or a kind of business such as \"restaurant\" or \"bank branch\" (search_datasets names these)"
},
"datasets": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 150,
"minItems": 1,
"description": "Instead of dataset: several dataset slugs answered as one (one count, one preview, one price, one file)"
},
"order_by": {
"type": "object",
"required": [
"field"
],
"properties": {
"field": {
"type": "string"
},
"direction": {
"enum": [
"asc",
"desc"
],
"type": "string",
"description": "Default desc"
}
},
"description": "With limit: the order the slice is taken in, as a purchase takes it. Without it, nearest first with `near`, else file order.",
"additionalProperties": false
},
"area_where": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 6,
"description": "Only rows whose county/zip/state/metro meets a Census condition, each as \"<kind>:<attribute><op><value>\" (ops > >= < <= =; values accept 1M, 250k, $50,000, 10%), e.g. \"county:population>1000000\". Every clause must hold; the fact is the area's, not the row's, and it adds nothing to the price. Attributes: e.g. population, households, median_household_income, median_age, pct_65_plus, housing_units; Census ACS people, income, education and housing; businesses and jobs by NAICS sector (<sector>_establishments, <sector>_employees) or detailed code (naics_<code>_establishments / _employees / _payroll); population growth; NOAA climate normals and actuals; NOAA storm events; station weather normals; hourly weather normals; building stock; Zillow home values; Zillow rents; building permits; IRS tax returns; FEMA hazard risk; USDA farm census. Every key (11,012) with its label, unit and kinds: see /area-attributes.json."
},
"area_columns": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 6,
"description": "Census, NOAA, FEMA and USDA facts added to every row as columns named <kind>_<attribute>, each as \"<kind>:<attribute>,<attribute>\", e.g. \"county:population,median_household_income\" — the county / ZIP / metro / state figures beside each location, in the preview and in the file you buy, after the area's id and name (county_fips, county_name; zip_code; metro_cbsa, metro_name; state_code, state_name). Free. The same attribute words area_where takes (listed there)."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}| rows | integer | Rows to return (default 10; with filters default 3, up to the published sample's size — samplePublished in the answer) |
| slug | string | Dataset slug. Or datasets / category to preview several at once. |
| metro | string | Only rows in one metro area (CBSA): its 5-digit code ("37980") or its name ("Philadelphia", "Philadelphia, PA"). The same as areas_in {"by": "metro", "ids": [code]}: rows are placed the way count_by_area places them, so "all hospitals in the Philadelphia metro" is one count, one price and one purcha… |
| shape | string | CRM-ready columns: hubspot (Company name, Company domain name, Website URL, Phone number, Street address, Street address 2, City, State/Region, Postal code, Country/Region, Industry, Description) or salesforce (Name, Website, Phone, BillingStreet, BillingCity, BillingState, BillingPostalCode, Billin… |
| state | string | Shortcut for where state eq <value>. Two-letter code; several states comma-separated ("VA,NC,SC") are one `in`. |
| total | integer | With datasets or category: rows wanted across all of them, split in proportion to each dataset's matches |
| where | array | Conditions on any column, all of which must hold. Blank cells never satisfy a comparison (the answer counts rows excluded only for that, and a small answer says what each condition removed). |
| county | string | Shortcut for where county eq <value> |
| exclude | array | With category or datasets: dataset slugs left out (a category minus one of its members, e.g. a list's competitors are its own category with itself excluded) |
| permits | object | Only rows with a building permit nearby, read live from the city's own permit register at question time — e.g. {"dataset": "<slug>", "city": "Austin", "state": "TX", "permits": {"days": 90, "type": "commercial", "min_usd": 1000000}}. One city register per question (from the base set's city, a ZIP in… |
| areas_in | object | Only rows in these areas, e.g. {"by": "county", "ids": ["18039"]} for Elkhart County, IN — the ids count_by_area returns. Rows are placed by county_fips, county + state, coordinates or ZIP, the same as count_by_area. |
| category | string | Instead of dataset: every dataset of one kind — "retail" (store chains), an industry or subcategory, or a kind of business such as "restaurant" or "bank branch" (search_datasets names these) |
| datasets | array | Instead of dataset: several dataset slugs answered as one (one count, one preview, one price, one file) |
| area_where | array | Only rows whose county/zip/state/metro meets a Census condition, each as "<kind>:<attribute><op><value>" (ops > >= < <= =; values accept 1M, 250k, $50,000, 10%), e.g. "county:population>1000000". Every clause must hold; the fact is the area's, not the row's, and it adds nothing to the price. Attribu… |
| area_columns | array | Census, NOAA, FEMA and USDA facts added to every row as columns named <kind>_<attribute>, each as "<kind>:<attribute>,<attribute>", e.g. "county:population,median_household_income" — the county / ZIP / metro / state figures beside each location, in the preview and in the file you buy, after the area… |
{
"name": "get_sample",
"title": "Get sample rows",
"description": "Free. Real rows from the live file, as JSON plus CSV text. Show these to the user so they can judge the fields and quality. Without filters: up to 10 rows spread across the whole dataset. With filters (the same ones count_locations takes: city, state, county, zip, metro, `where` on any column, areas_in (county / ZIP / metro / state ids from count_by_area), area_where, area_columns (Census figures as columns on every row), or `near` a place such as {place: \"Los Angeles, CA\", radius_miles: 25} on lists with coordinates): how many rows match, plus the list's FIXED free sample rows — the same published rows whatever the filter, each marked matches_your_question, the ones this filter matched FIRST (default 3 rows; rows up to the published sample's size shows them all, and samplePublished / sampleMatched say how many that is) — so the user can see real stores and the real column shape before deciding, with the exact count and price of the matches. The rows shown are fixed per list so that free answers cannot be composed into the file; the count, the coverage, the columns and the price are exact for the filter. To see what KINDS of place make up a count in an area (dealers vs manufacturers, say), use count_by_area with top_values on a class column. The result's `next` says exactly how to get every matching row. To preview several chains at once, pass datasets or category (e.g. \"retail\" or \"restaurant\") instead of slug: one combined answer with counts per dataset, duplicates removed and up to 3 rows across them. shape: hubspot | salesforce returns the same rows with that CRM's import column names first (the exact header row the paid file will have with the same shape), every other column after.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"zip": {
"type": "string",
"description": "Shortcut for where zip eq <value>"
},
"city": {
"type": "string",
"description": "Shortcut for where city eq <value>"
},
"near": {
"type": "object",
"properties": {
"lat": {
"type": "number"
},
"lng": {
"type": "number"
},
"zip": {
"type": "string",
"description": "5-digit zip"
},
"place": {
"type": "string",
"description": "City or town with state, e.g. \"Topeka, KS\" (a neighborhood or misspelling falls back to the nearest Census place name, and the answer says which)."
},
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"lat": {
"$ref": "#/properties/near/properties/lat"
},
"lng": {
"$ref": "#/properties/near/properties/lng"
},
"zip": {
"$ref": "#/properties/near/properties/zip"
},
"place": {
"type": "string",
"description": "City or town with state, e.g. \"Topeka, KS\""
}
},
"additionalProperties": false
},
"maxItems": 10,
"minItems": 1,
"description": "Several points instead of one place/zip/lat+lng (at most 10): a row counts when it is within the radius of ANY of them, e.g. an operator's offices."
},
"radius_miles": {
"type": "number",
"maximum": 500,
"description": "Only rows within this straight-line distance of the point (or of any of the points). Free.",
"exclusiveMinimum": 0
}
},
"description": "Distance search on lists with map coordinates (distanceSearch in search results): one of place, zip, lat+lng or `points` (within reach of any of them). Rows come back nearest first with a distance_miles column (straight line; no drive time); limit for 'the 10 closest', radius_miles for 'everything within 25 miles'. Rows without coordinates are excluded and counted.",
"additionalProperties": false
},
"rows": {
"type": "integer",
"maximum": 10,
"minimum": 1,
"description": "Rows to return (default 10; with filters default 3, up to the published sample's size — samplePublished in the answer)"
},
"slug": {
"type": "string",
"description": "Dataset slug. Or datasets / category to preview several at once."
},
"metro": {
"type": "string",
"description": "Only rows in one metro area (CBSA): its 5-digit code (\"37980\") or its name (\"Philadelphia\", \"Philadelphia, PA\"). The same as areas_in {\"by\": \"metro\", \"ids\": [code]}: rows are placed the way count_by_area places them, so \"all hospitals in the Philadelphia metro\" is one count, one price and one purchase."
},
"shape": {
"enum": [
"hubspot",
"salesforce"
],
"type": "string",
"description": "CRM-ready columns: hubspot (Company name, Company domain name, Website URL, Phone number, Street address, Street address 2, City, State/Region, Postal code, Country/Region, Industry, Description) or salesforce (Name, Website, Phone, BillingStreet, BillingCity, BillingState, BillingPostalCode, BillingCountry, Industry, Description) first, then every other column of the list under its own name. Nothing is dropped; a CRM column the list lacks is present and blank."
},
"state": {
"type": "string",
"description": "Shortcut for where state eq <value>. Two-letter code; several states comma-separated (\"VA,NC,SC\") are one `in`."
},
"total": {
"type": "integer",
"maximum": 10000,
"minimum": 1,
"description": "With datasets or category: rows wanted across all of them, split in proportion to each dataset's matches"
},
"where": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"op"
],
"properties": {
"op": {
"enum": [
"eq",
"ne",
"gt",
"gte",
"lt",
"lte",
"in",
"contains",
"starts_with",
"is_blank",
"not_blank",
"not_contains",
"not_in",
"any_of"
],
"type": "string",
"description": "eq/ne: case-insensitive (numeric when both sides are numbers; yes/true/y/1 are one answer). gt/gte/lt/lte: numeric, else text order (ISO dates work). in/not_in: value is an array. contains/not_contains/starts_with: text. is_blank/not_blank: no value (N/A, <UNAVAIL> count as blank). any_of: no value; kept when any condition in any_of holds."
},
"field": {
"type": "string",
"description": "Column name as listed by get_dataset (columns[].name), e.g. revenue_amt"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "array",
"items": {
"type": [
"string",
"number"
]
}
}
]
},
"any_of": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"op"
],
"properties": {
"op": {
"enum": [
"eq",
"ne",
"gt",
"gte",
"lt",
"lte",
"in",
"contains",
"starts_with",
"is_blank",
"not_blank",
"not_contains",
"not_in",
"any_of"
],
"type": "string"
},
"field": {
"type": "string"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "array",
"items": {
"type": [
"string",
"number"
]
}
}
]
}
},
"additionalProperties": false
},
"maxItems": 12,
"description": "With op any_of: the conditions, any one of which keeps the row."
}
},
"additionalProperties": false
},
"maxItems": 12,
"description": "Conditions on any column, all of which must hold. Blank cells never satisfy a comparison (the answer counts rows excluded only for that, and a small answer says what each condition removed)."
},
"county": {
"type": "string",
"description": "Shortcut for where county eq <value>"
},
"exclude": {
"type": "array",
"items": {
"type": "string"
},
"description": "With category or datasets: dataset slugs left out (a category minus one of its members, e.g. a list's competitors are its own category with itself excluded)"
},
"permits": {
"type": "object",
"properties": {
"days": {
"type": "integer",
"maximum": 3650,
"minimum": 1,
"description": "Issued in the last N days (default 365)"
},
"type": {
"enum": [
"any",
"new_construction",
"commercial",
"residential",
"renovation",
"demolition",
"electrical",
"plumbing",
"mechanical",
"roofing",
"solar",
"sign",
"pool"
],
"type": "string",
"description": "The kind of permit (default any)"
},
"metres": {
"type": "integer",
"maximum": 200,
"minimum": 10,
"description": "How close a permit must be to the row, in metres (default 60)"
},
"min_usd": {
"type": "number",
"minimum": 0,
"description": "Valuation at least this many dollars"
}
},
"description": "Only rows with a building permit nearby, read live from the city's own permit register at question time — e.g. {\"dataset\": \"<slug>\", \"city\": \"Austin\", \"state\": \"TX\", \"permits\": {\"days\": 90, \"type\": \"commercial\", \"min_usd\": 1000000}}. One city register per question (from the base set's city, a ZIP in it, its county, or a state with one register); the cities read now: New York, NY; Los Angeles, CA; Chicago, IL; Dallas, TX; Austin, TX; San Francisco, CA; Seattle, WA; Nashville, TN. A kind or amount a register cannot tell is refused in words, never answered as any. Free: counts, a preview, the price of the matching rows; the openData block names the register, its publisher, licence and when it was read. On /find: &permits=1&permits_days=90&permits_type=commercial&permits_min_usd=1000000. Not sold through a checkout yet: the answer's link is the page.",
"additionalProperties": false
},
"areas_in": {
"type": "object",
"required": [
"by",
"ids"
],
"properties": {
"by": {
"enum": [
"county",
"zip",
"state",
"metro"
],
"type": "string"
},
"ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 200,
"minItems": 1,
"description": "County FIPS, 5-digit ZIP, CBSA code or state code — the `id` of a count_by_area row"
}
},
"description": "Only rows in these areas, e.g. {\"by\": \"county\", \"ids\": [\"18039\"]} for Elkhart County, IN — the ids count_by_area returns. Rows are placed by county_fips, county + state, coordinates or ZIP, the same as count_by_area.",
"additionalProperties": false
},
"category": {
"type": "string",
"description": "Instead of dataset: every dataset of one kind — \"retail\" (store chains), an industry or subcategory, or a kind of business such as \"restaurant\" or \"bank branch\" (search_datasets names these)"
},
"datasets": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 150,
"minItems": 1,
"description": "Instead of dataset: several dataset slugs answered as one (one count, one preview, one price, one file)"
},
"area_where": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 6,
"description": "Only rows whose county/zip/state/metro meets a Census condition, each as \"<kind>:<attribute><op><value>\" (ops > >= < <= =; values accept 1M, 250k, $50,000, 10%), e.g. \"county:population>1000000\". Every clause must hold; the fact is the area's, not the row's, and it adds nothing to the price. Attributes: e.g. population, households, median_household_income, median_age, pct_65_plus, housing_units; Census ACS people, income, education and housing; businesses and jobs by NAICS sector (<sector>_establishments, <sector>_employees) or detailed code (naics_<code>_establishments / _employees / _payroll); population growth; NOAA climate normals and actuals; NOAA storm events; station weather normals; hourly weather normals; building stock; Zillow home values; Zillow rents; building permits; IRS tax returns; FEMA hazard risk; USDA farm census. Every key (11,012) with its label, unit and kinds: see /area-attributes.json."
},
"area_columns": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 6,
"description": "Census, NOAA, FEMA and USDA facts added to every row as columns named <kind>_<attribute>, each as \"<kind>:<attribute>,<attribute>\", e.g. \"county:population,median_household_income\" — the county / ZIP / metro / state figures beside each location, in the preview and in the file you buy, after the area's id and name (county_fips, county_name; zip_code; metro_cbsa, metro_name; state_code, state_name). Free. The same attribute words area_where takes (listed there)."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}{
"name": "request_list",
"title": "Request a new list",
"description": "Ask LocationLists to add a list we do not have yet. Use it when search_datasets finds nothing that fits, or the user wants a brand, place or kind of business we do not publish. Before calling: ask the user whether to send the request, and ask for their email so we can tell them when the list is ready. Pass an email only if the user gave it to you in this conversation; never guess or invent one. Called with neither email nor email_declined, it sends nothing and asks for the email. The request goes to the LocationLists team, the same place as the request box on locationlists.com. We add new datasets every day and prioritize requested ones; there is no promised date. Free, nothing is charged.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"topic"
],
"properties": {
"name": {
"type": "string",
"description": "The user's name, if they gave it"
},
"email": {
"type": "string",
"description": "The user's email, only if they gave it, so we can tell them when the list is ready"
},
"topic": {
"type": "string",
"description": "The list the user wants, in their words (2-200 characters)"
},
"company": {
"type": "string",
"description": "The user's company, if they gave it"
},
"details": {
"type": "string",
"description": "Anything else they specified: places, fields needed (phone, website, email), timing"
},
"use_case": {
"type": "string",
"description": "What they will use the list for, if they said (e.g. sales outreach, territory planning)"
},
"email_declined": {
"type": "boolean",
"description": "True only when you asked the user for their email and they chose not to leave one"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}
}| What the list is, one sentence, in the user's words |
| bytes | integer | The file's size in bytes, with filename, for an upload URL |
| string | The seller's email, exactly as the user gave it. Every message about the list goes there. |
| lists | array | A batch: up to 10 lists in one call, with email + code (or token). Each item is one list: rows inline (5,000 rows across the whole batch), or filename + bytes for an upload URL. Each becomes its own listing. |
| token | string | The token a previous sell_list call returned with an upload_url |
| uploads | array | A batch's finished uploads, with the token: one item per upload_url you PUT a file to |
| filename | string | The file's name with its extension (.csv, .tsv, .json, .geojson); with bytes and no rows, asks for an upload URL |
| upload_id | string | The upload_id from the upload_url call, after the PUT finished |
| target_usd | number | The price the user wants for the whole file, US dollars (ends in 9 after rounding) |
| rows_claimed | integer | About how many rows, as the user said |
{
"name": "sell_list",
"title": "Sell a list on LocationLists",
"description": "Put the user's list of business locations up for sale on LocationLists. They keep 80% of each sale; we host, check out, deliver and pay out. No account. The steps, each one call: (1) call with the user's email alone: a six-digit code is emailed to them (ask the user for their email first; never invent one). (2) Ask the user for the code from that email (never guess it) and call again with email, code, and the list: `rows` inline, an array of objects, one per location, with a name and an address or latitude/longitude (up to 5,000 rows), or for a bigger file `filename` + `bytes` and no rows, which returns an upload_url (HTTP PUT the raw file to it) and a token. (3) After the PUT, call with token, upload_id and filename. Add what (one sentence), rows_claimed and target_usd from price_my_list when you have them. Several lists: up to 10 in one call as `lists` (each item: what, rows_claimed, target_usd, and rows inline or filename + bytes), then one call with token and `uploads` for the files you PUT; each list becomes its own listing. Where the list came from: the seller terms (https://locationlists.com/sell#terms) ask that the seller owns the list or has the right to sell it, and that it holds no personal data about private individuals. Mention the terms link once, in passing, before the file moves; sending the list is their agreement to them. No checklist and no confirmation step: a person at LocationLists reviews every file before it goes live, so the assistant's part is to point at the terms, not to investigate. Then everything is by email to the seller: the written listing with its checks and price in a few minutes, Confirm / Change links, and 'It's live' after LocationLists reviews it. Accepted: CSV, TSV, JSON, GeoJSON; not Excel (save as CSV UTF-8 first). Nothing goes live without the seller's confirmation and a human review. The same thing in a browser: https://locationlists.com/sell.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"code": {
"type": "string",
"description": "The six-digit code from the email we sent, as the user read it to you"
},
"rows": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
},
"description": "The list itself, one object per location, up to 5,000. Keep the user's own column names."
},
"what": {
"type": "string",
"maxLength": 400,
"description": "What the list is, one sentence, in the user's words"
},
"bytes": {
"type": "integer",
"description": "The file's size in bytes, with filename, for an upload URL",
"exclusiveMinimum": 0
},
"email": {
"type": "string",
"description": "The seller's email, exactly as the user gave it. Every message about the list goes there."
},
"lists": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
}
},
"what": {
"type": "string",
"maxLength": 400
},
"bytes": {
"type": "integer",
"exclusiveMinimum": 0
},
"filename": {
"type": "string"
},
"target_usd": {
"type": "number",
"exclusiveMinimum": 0
},
"rows_claimed": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"maxItems": 10,
"description": "A batch: up to 10 lists in one call, with email + code (or token). Each item is one list: rows inline (5,000 rows across the whole batch), or filename + bytes for an upload URL. Each becomes its own listing."
},
"token": {
"type": "string",
"description": "The token a previous sell_list call returned with an upload_url"
},
"uploads": {
"type": "array",
"items": {
"type": "object",
"required": [
"upload_id",
"filename"
],
"properties": {
"what": {
"type": "string",
"maxLength": 400
},
"filename": {
"type": "string"
},
"upload_id": {
"type": "string"
},
"target_usd": {
"type": "number",
"exclusiveMinimum": 0
},
"rows_claimed": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"maxItems": 10,
"description": "A batch's finished uploads, with the token: one item per upload_url you PUT a file to"
},
"filename": {
"type": "string",
"description": "The file's name with its extension (.csv, .tsv, .json, .geojson); with bytes and no rows, asks for an upload URL"
},
"upload_id": {
"type": "string",
"description": "The upload_id from the upload_url call, after the PUT finished"
},
"target_usd": {
"type": "number",
"description": "The price the user wants for the whole file, US dollars (ends in 9 after rounding)",
"exclusiveMinimum": 0
},
"rows_claimed": {
"type": "integer",
"description": "About how many rows, as the user said",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}
}| total | integer | With datasets or category: rows wanted across all of them, split in proportion to each dataset's matches |
| where | array | Conditions on any column, all of which must hold. Blank cells never satisfy a comparison (the answer counts rows excluded only for that, and a small answer says what each condition removed). |
| county | string | Shortcut for where county eq <value> |
| dataset | string | Dataset slug, e.g. nonprofits-va. To combine several, give datasets or category instead. |
| exclude | array | With category or datasets: dataset slugs left out (a category minus one of its members, e.g. a list's competitors are its own category with itself excluded) |
| permits | object | Only rows with a building permit nearby, read live from the city's own permit register at question time — e.g. {"dataset": "<slug>", "city": "Austin", "state": "TX", "permits": {"days": 90, "type": "commercial", "min_usd": 1000000}}. One city register per question (from the base set's city, a ZIP in… |
| areas_in | object | Only rows in these areas, e.g. {"by": "county", "ids": ["18039"]} for Elkhart County, IN — the ids count_by_area returns. Rows are placed by county_fips, county + state, coordinates or ZIP, the same as count_by_area. |
| category | string | Instead of dataset: every dataset of one kind — "retail" (store chains), an industry or subcategory, or a kind of business such as "restaurant" or "bank branch" (search_datasets names these) |
| datasets | array | Instead of dataset: several dataset slugs answered as one (one count, one preview, one price, one file) |
| area_where | array | Only rows whose county/zip/state/metro meets a Census condition, each as "<kind>:<attribute><op><value>" (ops > >= < <= =; values accept 1M, 250k, $50,000, 10%), e.g. "county:population>1000000". Every clause must hold; the fact is the area's, not the row's, and it adds nothing to the price. Attribu… |
| area_columns | array | Census, NOAA, FEMA and USDA facts added to every row as columns named <kind>_<attribute>, each as "<kind>:<attribute>,<attribute>", e.g. "county:population,median_household_income" — the county / ZIP / metro / state figures beside each location, in the preview and in the file you buy, after the area… |
{
"name": "email_quote",
"title": "Email the user a quote (free)",
"description": "Free. Emails the user a plain-English quote for exactly this request: how many rows match, the card price, a few of the matches and a card checkout link, so they can pay later, from any device, or forward it to whoever holds the card. Takes the same arguments as count_locations: dataset, or datasets / category with total, plus filters. Before calling: ask the user for their email and whether to send it. Pass an email only if the user gave it to you in this conversation; never guess or invent one. Nothing is charged and nothing is bought; the price is checked again when they open the link.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"email"
],
"properties": {
"zip": {
"type": "string",
"description": "Shortcut for where zip eq <value>"
},
"city": {
"type": "string",
"description": "Shortcut for where city eq <value>"
},
"near": {
"type": "object",
"properties": {
"lat": {
"type": "number"
},
"lng": {
"type": "number"
},
"zip": {
"type": "string",
"description": "5-digit zip"
},
"place": {
"type": "string",
"description": "City or town with state, e.g. \"Topeka, KS\" (a neighborhood or misspelling falls back to the nearest Census place name, and the answer says which)."
},
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"lat": {
"$ref": "#/properties/near/properties/lat"
},
"lng": {
"$ref": "#/properties/near/properties/lng"
},
"zip": {
"$ref": "#/properties/near/properties/zip"
},
"place": {
"type": "string",
"description": "City or town with state, e.g. \"Topeka, KS\""
}
},
"additionalProperties": false
},
"maxItems": 10,
"minItems": 1,
"description": "Several points instead of one place/zip/lat+lng (at most 10): a row counts when it is within the radius of ANY of them, e.g. an operator's offices."
},
"radius_miles": {
"type": "number",
"maximum": 500,
"description": "Only rows within this straight-line distance of the point (or of any of the points). Free.",
"exclusiveMinimum": 0
}
},
"description": "Distance search on lists with map coordinates (distanceSearch in search results): one of place, zip, lat+lng or `points` (within reach of any of them). Rows come back nearest first with a distance_miles column (straight line; no drive time); limit for 'the 10 closest', radius_miles for 'everything within 25 miles'. Rows without coordinates are excluded and counted.",
"additionalProperties": false
},
"email": {
"type": "string",
"description": "The user's email, as they gave it"
},
"metro": {
"type": "string",
"description": "Only rows in one metro area (CBSA): its 5-digit code (\"37980\") or its name (\"Philadelphia\", \"Philadelphia, PA\"). The same as areas_in {\"by\": \"metro\", \"ids\": [code]}: rows are placed the way count_by_area places them, so \"all hospitals in the Philadelphia metro\" is one count, one price and one purchase."
},
"state": {
"type": "string",
"description": "Shortcut for where state eq <value>. Two-letter code; several states comma-separated (\"VA,NC,SC\") are one `in`."
},
"total": {
"type": "integer",
"maximum": 10000,
"minimum": 1,
"description": "With datasets or category: rows wanted across all of them, split in proportion to each dataset's matches"
},
"where": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"op"
],
"properties": {
"op": {
"enum": [
"eq",
"ne",
"gt",
"gte",
"lt",
"lte",
"in",
"contains",
"starts_with",
"is_blank",
"not_blank",
"not_contains",
"not_in",
"any_of"
],
"type": "string",
"description": "eq/ne: case-insensitive (numeric when both sides are numbers; yes/true/y/1 are one answer). gt/gte/lt/lte: numeric, else text order (ISO dates work). in/not_in: value is an array. contains/not_contains/starts_with: text. is_blank/not_blank: no value (N/A, <UNAVAIL> count as blank). any_of: no value; kept when any condition in any_of holds."
},
"field": {
"type": "string",
"description": "Column name as listed by get_dataset (columns[].name), e.g. revenue_amt"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "array",
"items": {
"type": [
"string",
"number"
]
}
}
]
},
"any_of": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"op"
],
"properties": {
"op": {
"enum": [
"eq",
"ne",
"gt",
"gte",
"lt",
"lte",
"in",
"contains",
"starts_with",
"is_blank",
"not_blank",
"not_contains",
"not_in",
"any_of"
],
"type": "string"
},
"field": {
"type": "string"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "array",
"items": {
"type": [
"string",
"number"
]
}
}
]
}
},
"additionalProperties": false
},
"maxItems": 12,
"description": "With op any_of: the conditions, any one of which keeps the row."
}
},
"additionalProperties": false
},
"maxItems": 12,
"description": "Conditions on any column, all of which must hold. Blank cells never satisfy a comparison (the answer counts rows excluded only for that, and a small answer says what each condition removed)."
},
"county": {
"type": "string",
"description": "Shortcut for where county eq <value>"
},
"dataset": {
"type": "string",
"description": "Dataset slug, e.g. nonprofits-va. To combine several, give datasets or category instead."
},
"exclude": {
"type": "array",
"items": {
"type": "string"
},
"description": "With category or datasets: dataset slugs left out (a category minus one of its members, e.g. a list's competitors are its own category with itself excluded)"
},
"permits": {
"type": "object",
"properties": {
"days": {
"type": "integer",
"maximum": 3650,
"minimum": 1,
"description": "Issued in the last N days (default 365)"
},
"type": {
"enum": [
"any",
"new_construction",
"commercial",
"residential",
"renovation",
"demolition",
"electrical",
"plumbing",
"mechanical",
"roofing",
"solar",
"sign",
"pool"
],
"type": "string",
"description": "The kind of permit (default any)"
},
"metres": {
"type": "integer",
"maximum": 200,
"minimum": 10,
"description": "How close a permit must be to the row, in metres (default 60)"
},
"min_usd": {
"type": "number",
"minimum": 0,
"description": "Valuation at least this many dollars"
}
},
"description": "Only rows with a building permit nearby, read live from the city's own permit register at question time — e.g. {\"dataset\": \"<slug>\", \"city\": \"Austin\", \"state\": \"TX\", \"permits\": {\"days\": 90, \"type\": \"commercial\", \"min_usd\": 1000000}}. One city register per question (from the base set's city, a ZIP in it, its county, or a state with one register); the cities read now: New York, NY; Los Angeles, CA; Chicago, IL; Dallas, TX; Austin, TX; San Francisco, CA; Seattle, WA; Nashville, TN. A kind or amount a register cannot tell is refused in words, never answered as any. Free: counts, a preview, the price of the matching rows; the openData block names the register, its publisher, licence and when it was read. On /find: &permits=1&permits_days=90&permits_type=commercial&permits_min_usd=1000000. Not sold through a checkout yet: the answer's link is the page.",
"additionalProperties": false
},
"areas_in": {
"type": "object",
"required": [
"by",
"ids"
],
"properties": {
"by": {
"enum": [
"county",
"zip",
"state",
"metro"
],
"type": "string"
},
"ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 200,
"minItems": 1,
"description": "County FIPS, 5-digit ZIP, CBSA code or state code — the `id` of a count_by_area row"
}
},
"description": "Only rows in these areas, e.g. {\"by\": \"county\", \"ids\": [\"18039\"]} for Elkhart County, IN — the ids count_by_area returns. Rows are placed by county_fips, county + state, coordinates or ZIP, the same as count_by_area.",
"additionalProperties": false
},
"category": {
"type": "string",
"description": "Instead of dataset: every dataset of one kind — \"retail\" (store chains), an industry or subcategory, or a kind of business such as \"restaurant\" or \"bank branch\" (search_datasets names these)"
},
"datasets": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 150,
"minItems": 1,
"description": "Instead of dataset: several dataset slugs answered as one (one count, one preview, one price, one file)"
},
"area_where": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 6,
"description": "Only rows whose county/zip/state/metro meets a Census condition, each as \"<kind>:<attribute><op><value>\" (ops > >= < <= =; values accept 1M, 250k, $50,000, 10%), e.g. \"county:population>1000000\". Every clause must hold; the fact is the area's, not the row's, and it adds nothing to the price. Attributes: e.g. population, households, median_household_income, median_age, pct_65_plus, housing_units; Census ACS people, income, education and housing; businesses and jobs by NAICS sector (<sector>_establishments, <sector>_employees) or detailed code (naics_<code>_establishments / _employees / _payroll); population growth; NOAA climate normals and actuals; NOAA storm events; station weather normals; hourly weather normals; building stock; Zillow home values; Zillow rents; building permits; IRS tax returns; FEMA hazard risk; USDA farm census. Every key (11,012) with its label, unit and kinds: see /area-attributes.json."
},
"area_columns": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 6,
"description": "Census, NOAA, FEMA and USDA facts added to every row as columns named <kind>_<attribute>, each as \"<kind>:<attribute>,<attribute>\", e.g. \"county:population,median_household_income\" — the county / ZIP / metro / state figures beside each location, in the preview and in the file you buy, after the area's id and name (county_fips, county_name; zip_code; metro_cbsa, metro_name; state_code, state_name). Free. The same attribute words area_where takes (listed there)."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}
}| Most rows to buy (max 10,000). Default: every match up to the max. Priced on the rows that actually match, never more. |
| metro | string | Only rows in one metro area (CBSA): its 5-digit code ("37980") or its name ("Philadelphia", "Philadelphia, PA"). The same as areas_in {"by": "metro", "ids": [code]}: rows are placed the way count_by_area places them, so "all hospitals in the Philadelphia metro" is one count, one price and one purcha… |
| shape | string | CRM-ready columns: hubspot (Company name, Company domain name, Website URL, Phone number, Street address, Street address 2, City, State/Region, Postal code, Country/Region, Industry, Description) or salesforce (Name, Website, Phone, BillingStreet, BillingCity, BillingState, BillingPostalCode, Billin… |
| state | string | Shortcut for where state eq <value>. Two-letter code; several states comma-separated ("VA,NC,SC") are one `in`. |
| total | integer | With datasets or category: rows wanted across all of them, split in proportion to each dataset's matches |
| where | array | Conditions on any column, all of which must hold. Blank cells never satisfy a comparison (the answer counts rows excluded only for that, and a small answer says what each condition removed). |
| county | string | Shortcut for where county eq <value> |
| relate | object |
| dataset | string | Dataset slug, e.g. nonprofits-va. To combine several, give datasets or category instead. |
| exclude | array | With category or datasets: dataset slugs left out (a category minus one of its members, e.g. a list's competitors are its own category with itself excluded) |
| permits | object | Only rows with a building permit nearby, read live from the city's own permit register at question time — e.g. {"dataset": "<slug>", "city": "Austin", "state": "TX", "permits": {"days": 90, "type": "commercial", "min_usd": 1000000}}. One city register per question (from the base set's city, a ZIP in… |
| areas_in | object | Only rows in these areas, e.g. {"by": "county", "ids": ["18039"]} for Elkhart County, IN — the ids count_by_area returns. Rows are placed by county_fips, county + state, coordinates or ZIP, the same as count_by_area. |
| category | string | Instead of dataset: every dataset of one kind — "retail" (store chains), an industry or subcategory, or a kind of business such as "restaurant" or "bank branch" (search_datasets names these) |
| datasets | array | Instead of dataset: several dataset slugs answered as one (one count, one preview, one price, one file) |
| order_by | object | Return the top rows by one column, e.g. {field: 'revenue_amt'} for the largest first. Blanks sort last. |
| area_where | array | Only rows whose county/zip/state/metro meets a Census condition, each as "<kind>:<attribute><op><value>" (ops > >= < <= =; values accept 1M, 250k, $50,000, 10%), e.g. "county:population>1000000". Every clause must hold; the fact is the area's, not the row's, and it adds nothing to the price. Attribu… |
| area_columns | array | Census, NOAA, FEMA and USDA facts added to every row as columns named <kind>_<attribute>, each as "<kind>:<attribute>,<attribute>", e.g. "county:population,median_household_income" — the county / ZIP / metro / state figures beside each location, in the preview and in the file you buy, after the area… |
{
"name": "create_query_checkout",
"title": "Card checkout for filtered rows",
"description": "For buyers paying by card: opens a Stripe Checkout for just the rows of one dataset that match a filter, and returns the payment URL to give the user. Takes the same filters as count_locations (state/city/county/zip, `where` on any column, `near`, `order_by`) and up to 10,000 rows. It counts the matches first, so the buyer pays only for rows that exist: the data price is the same per-row price query_locations charges, plus a card processing fee (2.9% + $0.30) added on top, one price the buyer sees at checkout. After payment the buyer is emailed a CSV download link; check_order with the session id returns it too. No match, a bad column, a distance search on a list without coordinates, or a subset that would cost more than the whole file returns an explanation and creates no checkout — nothing is charged. An agent that pays for itself should call query_locations instead. To cover several chains near one place, pass datasets or category and a total instead of dataset: one answer, one price and one checkout for one CSV (source_dataset names each row's dataset, duplicates removed). shape: hubspot | salesforce delivers the CSV with that CRM's import column names first (the download link also takes ?shape= later).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"zip": {
"type": "string",
"description": "Shortcut for where zip eq <value>"
},
"city": {
"type": "string",
"description": "Shortcut for where city eq <value>"
},
"near": {
"type": "object",
"properties": {
"lat": {
"type": "number"
},
"lng": {
"type": "number"
},
"zip": {
"type": "string",
"description": "5-digit zip"
},
"place": {
"type": "string",
"description": "City or town with state, e.g. \"Topeka, KS\" (a neighborhood or misspelling falls back to the nearest Census place name, and the answer says which)."
},
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"lat": {
"$ref": "#/properties/near/properties/lat"
},
"lng": {
"$ref": "#/properties/near/properties/lng"
},
"zip": {
"$ref": "#/properties/near/properties/zip"
},
"place": {
"type": "string",
"description": "City or town with state, e.g. \"Topeka, KS\""
}
},
"additionalProperties": false
},
"maxItems": 10,
"minItems": 1,
"description": "Several points instead of one place/zip/lat+lng (at most 10): a row counts when it is within the radius of ANY of them, e.g. an operator's offices."
},
"radius_miles": {
"type": "number",
"maximum": 500,
"description": "Only rows within this straight-line distance of the point (or of any of the points). Free.",
"exclusiveMinimum": 0
}
},
"description": "Distance search on lists with map coordinates (distanceSearch in search results): one of place, zip, lat+lng or `points` (within reach of any of them). Rows come back nearest first with a distance_miles column (straight line; no drive time); limit for 'the 10 closest', radius_miles for 'everything within 25 miles'. Rows without coordinates are excluded and counted.",
"additionalProperties": false
},
"email": {
"type": "string",
"format": "email",
"description": "Buyer email, if known — prefills Checkout and is where the download link is sent"
},
"limit": {
"type": "integer",
"maximum": 10000,
"minimum": 1,
"description": "Most rows to buy (max 10,000). Default: every match up to the max. Priced on the rows that actually match, never more."
},
"metro": {
"type": "string",
"description": "Only rows in one metro area (CBSA): its 5-digit code (\"37980\") or its name (\"Philadelphia\", \"Philadelphia, PA\"). The same as areas_in {\"by\": \"metro\", \"ids\": [code]}: rows are placed the way count_by_area places them, so \"all hospitals in the Philadelphia metro\" is one count, one price and one purchase."
},
"shape": {
"enum": [
"hubspot",
"salesforce"
],
"type": "string",
"description": "CRM-ready columns: hubspot (Company name, Company domain name, Website URL, Phone number, Street address, Street address 2, City, State/Region, Postal code, Country/Region, Industry, Description) or salesforce (Name, Website, Phone, BillingStreet, BillingCity, BillingState, BillingPostalCode, BillingCountry, Industry, Description) first, then every other column of the list under its own name. Nothing is dropped; a CRM column the list lacks is present and blank."
},
"state": {
"type": "string",
"description": "Shortcut for where state eq <value>. Two-letter code; several states comma-separated (\"VA,NC,SC\") are one `in`."
},
"total": {
"type": "integer",
"maximum": 10000,
"minimum": 1,
"description": "With datasets or category: rows wanted across all of them, split in proportion to each dataset's matches"
},
"where": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"op"
],
"properties": {
"op": {
"enum": [
"eq",
"ne",
"gt",
"gte",
"lt",
"lte",
"in",
"contains",
"starts_with",
"is_blank",
"not_blank",
"not_contains",
"not_in",
"any_of"
],
"type": "string",
"description": "eq/ne: case-insensitive (numeric when both sides are numbers; yes/true/y/1 are one answer). gt/gte/lt/lte: numeric, else text order (ISO dates work). in/not_in: value is an array. contains/not_contains/starts_with: text. is_blank/not_blank: no value (N/A, <UNAVAIL> count as blank). any_of: no value; kept when any condition in any_of holds."
},
"field": {
"type": "string",
"description": "Column name as listed by get_dataset (columns[].name), e.g. revenue_amt"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "array",
"items": {
"type": [
"string",
"number"
]
}
}
]
},
"any_of": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"op"
],
"properties": {
"op": {
"enum": [
"eq",
"ne",
"gt",
"gte",
"lt",
"lte",
"in",
"contains",
"starts_with",
"is_blank",
"not_blank",
"not_contains",
"not_in",
"any_of"
],
"type": "string"
},
"field": {
"type": "string"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "array",
"items": {
"type": [
"string",
"number"
]
}
}
]
}
},
"additionalProperties": false
},
"maxItems": 12,
"description": "With op any_of: the conditions, any one of which keeps the row."
}
},
"additionalProperties": false
},
"maxItems": 12,
"description": "Conditions on any column, all of which must hold. Blank cells never satisfy a comparison (the answer counts rows excluded only for that, and a small answer says what each condition removed)."
},
"county": {
"type": "string",
"description": "Shortcut for where county eq <value>"
},
"relate": {
"type": "object",
"additionalProperties": {}
},
"dataset": {
"type": "string",
"description": "Dataset slug, e.g. nonprofits-va. To combine several, give datasets or category instead."
},
"exclude": {
"type": "array",
"items": {
"type": "string"
},
"description": "With category or datasets: dataset slugs left out (a category minus one of its members, e.g. a list's competitors are its own category with itself excluded)"
},
"permits": {
"type": "object",
"properties": {
"days": {
"type": "integer",
"maximum": 3650,
"minimum": 1,
"description": "Issued in the last N days (default 365)"
},
"type": {
"enum": [
"any",
"new_construction",
"commercial",
"residential",
"renovation",
"demolition",
"electrical",
"plumbing",
"mechanical",
"roofing",
"solar",
"sign",
"pool"
],
"type": "string",
"description": "The kind of permit (default any)"
},
"metres": {
"type": "integer",
"maximum": 200,
"minimum": 10,
"description": "How close a permit must be to the row, in metres (default 60)"
},
"min_usd": {
"type": "number",
"minimum": 0,
"description": "Valuation at least this many dollars"
}
},
"description": "Only rows with a building permit nearby, read live from the city's own permit register at question time — e.g. {\"dataset\": \"<slug>\", \"city\": \"Austin\", \"state\": \"TX\", \"permits\": {\"days\": 90, \"type\": \"commercial\", \"min_usd\": 1000000}}. One city register per question (from the base set's city, a ZIP in it, its county, or a state with one register); the cities read now: New York, NY; Los Angeles, CA; Chicago, IL; Dallas, TX; Austin, TX; San Francisco, CA; Seattle, WA; Nashville, TN. A kind or amount a register cannot tell is refused in words, never answered as any. Free: counts, a preview, the price of the matching rows; the openData block names the register, its publisher, licence and when it was read. On /find: &permits=1&permits_days=90&permits_type=commercial&permits_min_usd=1000000. Not sold through a checkout yet: the answer's link is the page.",
"additionalProperties": false
},
"areas_in": {
"type": "object",
"required": [
"by",
"ids"
],
"properties": {
"by": {
"enum": [
"county",
"zip",
"state",
"metro"
],
"type": "string"
},
"ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 200,
"minItems": 1,
"description": "County FIPS, 5-digit ZIP, CBSA code or state code — the `id` of a count_by_area row"
}
},
"description": "Only rows in these areas, e.g. {\"by\": \"county\", \"ids\": [\"18039\"]} for Elkhart County, IN — the ids count_by_area returns. Rows are placed by county_fips, county + state, coordinates or ZIP, the same as count_by_area.",
"additionalProperties": false
},
"category": {
"type": "string",
"description": "Instead of dataset: every dataset of one kind — \"retail\" (store chains), an industry or subcategory, or a kind of business such as \"restaurant\" or \"bank branch\" (search_datasets names these)"
},
"datasets": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 150,
"minItems": 1,
"description": "Instead of dataset: several dataset slugs answered as one (one count, one preview, one price, one file)"
},
"order_by": {
"type": "object",
"required": [
"field"
],
"properties": {
"field": {
"type": "string"
},
"direction": {
"enum": [
"asc",
"desc"
],
"type": "string",
"description": "Default desc"
}
},
"description": "Return the top rows by one column, e.g. {field: 'revenue_amt'} for the largest first. Blanks sort last.",
"additionalProperties": false
},
"area_where": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 6,
"description": "Only rows whose county/zip/state/metro meets a Census condition, each as \"<kind>:<attribute><op><value>\" (ops > >= < <= =; values accept 1M, 250k, $50,000, 10%), e.g. \"county:population>1000000\". Every clause must hold; the fact is the area's, not the row's, and it adds nothing to the price. Attributes: e.g. population, households, median_household_income, median_age, pct_65_plus, housing_units; Census ACS people, income, education and housing; businesses and jobs by NAICS sector (<sector>_establishments, <sector>_employees) or detailed code (naics_<code>_establishments / _employees / _payroll); population growth; NOAA climate normals and actuals; NOAA storm events; station weather normals; hourly weather normals; building stock; Zillow home values; Zillow rents; building permits; IRS tax returns; FEMA hazard risk; USDA farm census. Every key (11,012) with its label, unit and kinds: see /area-attributes.json."
},
"area_columns": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 6,
"description": "Census, NOAA, FEMA and USDA facts added to every row as columns named <kind>_<attribute>, each as \"<kind>:<attribute>,<attribute>\", e.g. \"county:population,median_household_income\" — the county / ZIP / metro / state figures beside each location, in the preview and in the file you buy, after the area's id and name (county_fips, county_name; zip_code; metro_cbsa, metro_name; state_code, state_name). Free. The same attribute words area_where takes (listed there)."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}
}| Parameter | Type | Description |
|---|---|---|
| zip | string | Shortcut for where zip eq <value> |
| city | string | Shortcut for where city eq <value> |
| near | object | Distance search on lists with map coordinates (distanceSearch in search results): one of place, zip, lat+lng or `points` (within reach of any of them). Rows come back nearest first with a distance_miles column (straight line; no drive time); limit for 'the 10 closest', radius_miles for 'everything w… |
| limit | integer | Rows to return and pay for. Default: every matching row, up to the most one call can return. That maximum depends on how wide the dataset's rows are, from 100 to 1,000; count_locations reports it as maxRowsPerCall, and a larger limit is reduced to it before pricing. |
| metro | string | Only rows in one metro area (CBSA): its 5-digit code ("37980") or its name ("Philadelphia", "Philadelphia, PA"). The same as areas_in {"by": "metro", "ids": [code]}: rows are placed the way count_by_area places them, so "all hospitals in the Philadelphia metro" is one count, one price and one purcha… |
| shape | string | CRM-ready columns: hubspot (Company name, Company domain name, Website URL, Phone number, Street address, Street address 2, City, State/Region, Postal code, Country/Region, Industry, Description) or salesforce (Name, Website, Phone, BillingStreet, BillingCity, BillingState, BillingPostalCode, Billin… |
| state | string | Shortcut for where state eq <value>. Two-letter code; several states comma-separated ("VA,NC,SC") are one `in`. |
| total | integer | With datasets or category: rows to return and pay for across all of them (default every distinct match, up to 1,000), in one payment |
| where | array | Conditions on any column, all of which must hold. Blank cells never satisfy a comparison (the answer counts rows excluded only for that, and a small answer says what each condition removed). |
| county | string | Shortcut for where county eq <value> |
| offset | integer | Skip this many matching rows, to page past the first call |
| relate | object | |
| dataset | string | Dataset slug, e.g. nonprofits-va. To combine several, give datasets or category instead. |
| exclude | array | With category or datasets: dataset slugs left out (a category minus one of its members, e.g. a list's competitors are its own category with itself excluded) |
| permits | object | Only rows with a building permit nearby, read live from the city's own permit register at question time — e.g. {"dataset": "<slug>", "city": "Austin", "state": "TX", "permits": {"days": 90, "type": "commercial", "min_usd": 1000000}}. One city register per question (from the base set's city, a ZIP in… |
| areas_in | object | Only rows in these areas, e.g. {"by": "county", "ids": ["18039"]} for Elkhart County, IN — the ids count_by_area returns. Rows are placed by county_fips, county + state, coordinates or ZIP, the same as count_by_area. |
| category | string | Instead of dataset: every dataset of one kind — "retail" (store chains), an industry or subcategory, or a kind of business such as "restaurant" or "bank branch" (search_datasets names these) |
| datasets | array | Instead of dataset: several dataset slugs answered as one (one count, one preview, one price, one file) |
| order_by | object | Return the top rows by one column, e.g. {field: 'revenue_amt'} for the largest first. Blanks sort last. |
| area_where | array | Only rows whose county/zip/state/metro meets a Census condition, each as "<kind>:<attribute><op><value>" (ops > >= < <= =; values accept 1M, 250k, $50,000, 10%), e.g. "county:population>1000000". Every clause must hold; the fact is the area's, not the row's, and it adds nothing to the price. Attribu… |
| area_columns | array | Census, NOAA, FEMA and USDA facts added to every row as columns named <kind>_<attribute>, each as "<kind>:<attribute>,<attribute>", e.g. "county:population,median_household_income" — the county / ZIP / metro / state figures beside each location, in the preview and in the file you buy, after the area… |
{
"name": "query_locations",
"title": "Query locations (paid)",
"description": "Return matching rows from one dataset, filtered on any of its columns — state/city/county/zip shortcuts plus `where` conditions with numeric comparisons (e.g. [{field:\"revenue_amt\",op:\"gt\",value:2000000}]), sorted with `order_by` and paged with `offset`. `near` ({place:\"Topeka, KS\"}, a zip, or lat+lng, optional radius_miles) returns the closest rows first with distance_miles, on lists with coordinates — so \"10 banks closest to Topeka\" is one call for 10 rows. get_dataset lists the columns; count_locations (free) tells you how many rows match and what fetching them costs before you pay. Priced per row and settled only after the rows are produced, so a failed call costs nothing. The rate is derived from the dataset: roughly 2x its list price spread over its record count, so a small slice of a big file is cents. By default you get and pay for every matching row, up to 100 to 1,000 rows per call depending on how wide the dataset's rows are (count_locations reports maxRowsPerCall); pass limit for fewer. Call it without payment first: the result is a payment-required quote (terms in the server instructions) with the exact amount and `quote` (the same rows, each source at its rate, as count_locations' slice), and nothing is charged until you retry with payment. A paid call is billed for the rows it returns: each row at its own list's per-row rate (an Overture open-data row at $0.005; a row of a chain LocationLists sells its own list for, at that list's rate), plus a $0.01 per-call fee, rounded once to the nearest cent, at least $0.02, never more than the whole list. count_locations with the same filters, limit and offset quotes exactly that page, row source by row source (price.breakdown), before anything is paid. How a list is sold: our own lists are sold as a whole file (create_checkout / buy_dataset), and those of 5,000 records or more are also sold by the row (query_locations / create_query_checkout); smaller lists are sold whole only. Open map data lists (soldBy \"row\" in get_dataset) are sold by the row only, at any size — there is no file to buy. One card checkout downloads up to 10,000 rows at once; up to 150,000 rows, an answer's buy link still sells them all, and the file is built after payment and its download link emailed. For more, buy the whole file where the list has one, narrow the question to a state, metro or area, or email kyle@locationlists.com for the whole file. To cover several chains near one place, pass datasets or category and a total (up to 1,000 rows) instead of dataset: one answer, one price and one file, with source_dataset naming each row's dataset and duplicates removed; inside a combined answer, small datasets are sold by the row too.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"zip": {
"type": "string",
"description": "Shortcut for where zip eq <value>"
},
"city": {
"type": "string",
"description": "Shortcut for where city eq <value>"
},
"near": {
"type": "object",
"properties": {
"lat": {
"type": "number"
},
"lng": {
"type": "number"
},
"zip": {
"type": "string",
"description": "5-digit zip"
},
"place": {
"type": "string",
"description": "City or town with state, e.g. \"Topeka, KS\" (a neighborhood or misspelling falls back to the nearest Census place name, and the answer says which)."
},
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"lat": {
"$ref": "#/properties/near/properties/lat"
},
"lng": {
"$ref": "#/properties/near/properties/lng"
},
"zip": {
"$ref": "#/properties/near/properties/zip"
},
"place": {
"type": "string",
"description": "City or town with state, e.g. \"Topeka, KS\""
}
},
"additionalProperties": false
},
"maxItems": 10,
"minItems": 1,
"description": "Several points instead of one place/zip/lat+lng (at most 10): a row counts when it is within the radius of ANY of them, e.g. an operator's offices."
},
"radius_miles": {
"type": "number",
"maximum": 500,
"description": "Only rows within this straight-line distance of the point (or of any of the points). Free.",
"exclusiveMinimum": 0
}
},
"description": "Distance search on lists with map coordinates (distanceSearch in search results): one of place, zip, lat+lng or `points` (within reach of any of them). Rows come back nearest first with a distance_miles column (straight line; no drive time); limit for 'the 10 closest', radius_miles for 'everything within 25 miles'. Rows without coordinates are excluded and counted.",
"additionalProperties": false
},
"limit": {
"type": "integer",
"maximum": 1000,
"minimum": 1,
"description": "Rows to return and pay for. Default: every matching row, up to the most one call can return. That maximum depends on how wide the dataset's rows are, from 100 to 1,000; count_locations reports it as maxRowsPerCall, and a larger limit is reduced to it before pricing."
},
"metro": {
"type": "string",
"description": "Only rows in one metro area (CBSA): its 5-digit code (\"37980\") or its name (\"Philadelphia\", \"Philadelphia, PA\"). The same as areas_in {\"by\": \"metro\", \"ids\": [code]}: rows are placed the way count_by_area places them, so \"all hospitals in the Philadelphia metro\" is one count, one price and one purchase."
},
"shape": {
"enum": [
"hubspot",
"salesforce"
],
"type": "string",
"description": "CRM-ready columns: hubspot (Company name, Company domain name, Website URL, Phone number, Street address, Street address 2, City, State/Region, Postal code, Country/Region, Industry, Description) or salesforce (Name, Website, Phone, BillingStreet, BillingCity, BillingState, BillingPostalCode, BillingCountry, Industry, Description) first, then every other column of the list under its own name. Nothing is dropped; a CRM column the list lacks is present and blank."
},
"state": {
"type": "string",
"description": "Shortcut for where state eq <value>. Two-letter code; several states comma-separated (\"VA,NC,SC\") are one `in`."
},
"total": {
"type": "integer",
"maximum": 1000,
"minimum": 1,
"description": "With datasets or category: rows to return and pay for across all of them (default every distinct match, up to 1,000), in one payment"
},
"where": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"op"
],
"properties": {
"op": {
"enum": [
"eq",
"ne",
"gt",
"gte",
"lt",
"lte",
"in",
"contains",
"starts_with",
"is_blank",
"not_blank",
"not_contains",
"not_in",
"any_of"
],
"type": "string",
"description": "eq/ne: case-insensitive (numeric when both sides are numbers; yes/true/y/1 are one answer). gt/gte/lt/lte: numeric, else text order (ISO dates work). in/not_in: value is an array. contains/not_contains/starts_with: text. is_blank/not_blank: no value (N/A, <UNAVAIL> count as blank). any_of: no value; kept when any condition in any_of holds."
},
"field": {
"type": "string",
"description": "Column name as listed by get_dataset (columns[].name), e.g. revenue_amt"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "array",
"items": {
"type": [
"string",
"number"
]
}
}
]
},
"any_of": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"op"
],
"properties": {
"op": {
"enum": [
"eq",
"ne",
"gt",
"gte",
"lt",
"lte",
"in",
"contains",
"starts_with",
"is_blank",
"not_blank",
"not_contains",
"not_in",
"any_of"
],
"type": "string"
},
"field": {
"type": "string"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "array",
"items": {
"type": [
"string",
"number"
]
}
}
]
}
},
"additionalProperties": false
},
"maxItems": 12,
"description": "With op any_of: the conditions, any one of which keeps the row."
}
},
"additionalProperties": false
},
"maxItems": 12,
"description": "Conditions on any column, all of which must hold. Blank cells never satisfy a comparison (the answer counts rows excluded only for that, and a small answer says what each condition removed)."
},
"county": {
"type": "string",
"description": "Shortcut for where county eq <value>"
},
"offset": {
"type": "integer",
"maximum": 10000,
"minimum": 0,
"description": "Skip this many matching rows, to page past the first call"
},
"relate": {
"type": "object",
"additionalProperties": {}
},
"dataset": {
"type": "string",
"description": "Dataset slug, e.g. nonprofits-va. To combine several, give datasets or category instead."
},
"exclude": {
"type": "array",
"items": {
"type": "string"
},
"description": "With category or datasets: dataset slugs left out (a category minus one of its members, e.g. a list's competitors are its own category with itself excluded)"
},
"permits": {
"type": "object",
"properties": {
"days": {
"type": "integer",
"maximum": 3650,
"minimum": 1,
"description": "Issued in the last N days (default 365)"
},
"type": {
"enum": [
"any",
"new_construction",
"commercial",
"residential",
"renovation",
"demolition",
"electrical",
"plumbing",
"mechanical",
"roofing",
"solar",
"sign",
"pool"
],
"type": "string",
"description": "The kind of permit (default any)"
},
"metres": {
"type": "integer",
"maximum": 200,
"minimum": 10,
"description": "How close a permit must be to the row, in metres (default 60)"
},
"min_usd": {
"type": "number",
"minimum": 0,
"description": "Valuation at least this many dollars"
}
},
"description": "Only rows with a building permit nearby, read live from the city's own permit register at question time — e.g. {\"dataset\": \"<slug>\", \"city\": \"Austin\", \"state\": \"TX\", \"permits\": {\"days\": 90, \"type\": \"commercial\", \"min_usd\": 1000000}}. One city register per question (from the base set's city, a ZIP in it, its county, or a state with one register); the cities read now: New York, NY; Los Angeles, CA; Chicago, IL; Dallas, TX; Austin, TX; San Francisco, CA; Seattle, WA; Nashville, TN. A kind or amount a register cannot tell is refused in words, never answered as any. Free: counts, a preview, the price of the matching rows; the openData block names the register, its publisher, licence and when it was read. On /find: &permits=1&permits_days=90&permits_type=commercial&permits_min_usd=1000000. Not sold through a checkout yet: the answer's link is the page.",
"additionalProperties": false
},
"areas_in": {
"type": "object",
"required": [
"by",
"ids"
],
"properties": {
"by": {
"enum": [
"county",
"zip",
"state",
"metro"
],
"type": "string"
},
"ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 200,
"minItems": 1,
"description": "County FIPS, 5-digit ZIP, CBSA code or state code — the `id` of a count_by_area row"
}
},
"description": "Only rows in these areas, e.g. {\"by\": \"county\", \"ids\": [\"18039\"]} for Elkhart County, IN — the ids count_by_area returns. Rows are placed by county_fips, county + state, coordinates or ZIP, the same as count_by_area.",
"additionalProperties": false
},
"category": {
"type": "string",
"description": "Instead of dataset: every dataset of one kind — \"retail\" (store chains), an industry or subcategory, or a kind of business such as \"restaurant\" or \"bank branch\" (search_datasets names these)"
},
"datasets": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 150,
"minItems": 1,
"description": "Instead of dataset: several dataset slugs answered as one (one count, one preview, one price, one file)"
},
"order_by": {
"type": "object",
"required": [
"field"
],
"properties": {
"field": {
"type": "string"
},
"direction": {
"enum": [
"asc",
"desc"
],
"type": "string",
"description": "Default desc"
}
},
"description": "Return the top rows by one column, e.g. {field: 'revenue_amt'} for the largest first. Blanks sort last.",
"additionalProperties": false
},
"area_where": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 6,
"description": "Only rows whose county/zip/state/metro meets a Census condition, each as \"<kind>:<attribute><op><value>\" (ops > >= < <= =; values accept 1M, 250k, $50,000, 10%), e.g. \"county:population>1000000\". Every clause must hold; the fact is the area's, not the row's, and it adds nothing to the price. Attributes: e.g. population, households, median_household_income, median_age, pct_65_plus, housing_units; Census ACS people, income, education and housing; businesses and jobs by NAICS sector (<sector>_establishments, <sector>_employees) or detailed code (naics_<code>_establishments / _employees / _payroll); population growth; NOAA climate normals and actuals; NOAA storm events; station weather normals; hourly weather normals; building stock; Zillow home values; Zillow rents; building permits; IRS tax returns; FEMA hazard risk; USDA farm census. Every key (11,012) with its label, unit and kinds: see /area-attributes.json."
},
"area_columns": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 6,
"description": "Census, NOAA, FEMA and USDA facts added to every row as columns named <kind>_<attribute>, each as \"<kind>:<attribute>,<attribute>\", e.g. \"county:population,median_household_income\" — the county / ZIP / metro / state figures beside each location, in the preview and in the file you buy, after the area's id and name (county_fips, county_name; zip_code; metro_cbsa, metro_name; state_code, state_name). Free. The same attribute words area_where takes (listed there)."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}