Count matching locations (free)
count_locationsRead-onlyIdempotent
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 or drive_minutes, on lists with coordinates. AREA DATA, free: area_where keeps rows whose county / ZIP / metro / state meets a Census condition (county:population>1000000), and area_columns adds those figures to every row as columns (county:population,median_household_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 USDC total, 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 USDC 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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | Shortcut for where zip eq <value> | |
| city | No | Shortcut for where city eq <value> | |
| near | No | Distance search, on lists with map coordinates (distanceSearch in search results): give ONE of place, zip, lat+lng, or `points` (several of those: within reach of ANY of them, distance to the nearest). Rows come back nearest first with a distance_miles column (straight line); combine with limit for 'the 10 closest', radius_miles for 'everything within 25 miles', or drive_minutes for 'everything within a 30-minute drive' (adds within_drive_minutes; 5-60 minutes; the routing provider draws no longer band, so a 2- or 4-hour reach is not available here — use the largest band, 60 minutes, or radius_miles). Give radius_miles or drive_minutes, not both. Rows without coordinates are excluded and counted. Drive time depends on an outside routing service: when an answer says drive-time search is unavailable or not switched on, ask the same question again with radius_miles (straight-line miles, always available, free). | |
| limit | No | 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 | No | 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 | No | Shortcut for where state eq <value>. Two-letter code. | |
| total | No | With datasets or category: rows wanted across all of them, split in proportion to each dataset's matches | |
| where | No | Conditions on any column, all of which must hold. Blank cells never satisfy a comparison; the response counts rows excluded only because a tested column was blank. A small or empty answer says how many rows each condition removed and what the column really holds. | |
| county | No | Shortcut for where county eq <value> | |
| offset | No | With limit: skip this many matching rows, as a paged purchase does, so the quote is for that page | |
| dataset | No | Dataset slug, e.g. nonprofits-va. To combine several, give datasets or category instead. | |
| exclude | No | 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 | No | 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}} for places near a commercial permit issued in the last 90 days valued at $1M or more. days: issued in the last N days (default 365, and the answer says the window was defaulted); type: one of any, new_construction, commercial, residential, renovation, demolition, electrical, plumbing, mechanical, roofing, solar, sign, pool; min_usd: the valuation floor; metres: how close a permit must be (default 60). One city register per question, chosen 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 city's register cannot tell is refused in words, never answered as any. The answer is free (counts, a preview, the price of the matching rows of our list) and its openData block names the register, its publisher, licence and when it was read. The same question 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. | |
| areas_in | No | 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 | No | 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 | No | Instead of dataset: several dataset slugs answered as one (one count, one preview, one price, one file) | |
| order_by | No | 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 | No | 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: population (population), households (households), median_household_income (median household income), median_age (median age), pct_65_plus (share of residents aged 65 or older), pct_bachelors_plus (share with a bachelor's degree or higher), housing_units (housing units), owner_occupied_share (owner-occupied share), median_home_value (median home value), establishments (business establishments), employees (employees), population_estimate (population estimate; county/metro/state only), population_growth_since_2020 (population growth since 2020; county/metro/state only); by NAICS sector, <sector>_establishments and <sector>_employees (employees: county/metro/state only) for agriculture, mining, utilities, construction, manufacturing, wholesale_trade, retail_trade, transportation, information, finance, real_estate, professional, management, administrative, educational_services, health_care, arts, accommodation, other_services; by detailed NAICS industry (1999 codes, 2 to 6 digits, the Census's titles), naics_<code>_establishments (county/metro/state/zip), naics_<code>_employees and naics_<code>_payroll (county/metro/state), e.g. naics_4471_establishments (gasoline stations naics 4471 establishments), naics_8111_establishments (automotive repair and maintenance establishments), naics_238990_establishments (all other specialty trade contractors naics 238990 establishments), naics_561621_establishments (security systems services except locksmiths establishments); 262 nclimdiv fields (NOAA nClimDiv county climate normals, 1991–2020, and 2025 actuals (release 2026-09-04)): january_high (January high), february_high (February high), march_high (March high), april_high (April high), may_high (May high), june_high (June high), …; 190 storms fields (NOAA Storm Events Database, 2016–2025, events a year by county): astronomical_low_tide_events (astronomical low tide events a year), avalanche_events (avalanche events a year), blizzard_events (blizzard events a year), coastal_flood_events (coastal flood events a year), cold_or_wind_chill_events (cold or wind chill events a year), debris_flow_events (debris flow events a year), …; 127 normals-annual fields (NOAA U.S. Climate Normals 1991–2020, annual and seasonal station normals, by county): annual_cooling_degree_days_base_40 (annual cooling degree days base 40), annual_cooling_degree_days_base_45 (annual cooling degree days base 45), annual_cooling_degree_days_base_50 (annual cooling degree days base 50), annual_cooling_degree_days_base_55 (annual cooling degree days base 55), annual_cooling_degree_days_base_57 (annual cooling degree days base 57), annual_cooling_degree_days_base_60 (annual cooling degree days base 60), …; 67 normals-winter fields (NOAA U.S. Climate Normals 1991–2020, annual and seasonal station normals, by county): winter_cooling_degree_days_base_40 (winter cooling degree days base 40), winter_cooling_degree_days_base_45 (winter cooling degree days base 45), winter_cooling_degree_days_base_50 (winter cooling degree days base 50), winter_cooling_degree_days_base_55 (winter cooling degree days base 55), winter_cooling_degree_days_base_57 (winter cooling degree days base 57), winter_cooling_degree_days_base_60 (winter cooling degree days base 60), …; 67 normals-spring fields (NOAA U.S. Climate Normals 1991–2020, annual and seasonal station normals, by county): spring_cooling_degree_days_base_40 (spring cooling degree days base 40), spring_cooling_degree_days_base_45 (spring cooling degree days base 45), spring_cooling_degree_days_base_50 (spring cooling degree days base 50), spring_cooling_degree_days_base_55 (spring cooling degree days base 55), spring_cooling_degree_days_base_57 (spring cooling degree days base 57), spring_cooling_degree_days_base_60 (spring cooling degree days base 60), …; 67 normals-summer fields (NOAA U.S. Climate Normals 1991–2020, annual and seasonal station normals, by county): summer_cooling_degree_days_base_40 (summer cooling degree days base 40), summer_cooling_degree_days_base_45 (summer cooling degree days base 45), summer_cooling_degree_days_base_50 (summer cooling degree days base 50), summer_cooling_degree_days_base_55 (summer cooling degree days base 55), summer_cooling_degree_days_base_57 (summer cooling degree days base 57), summer_cooling_degree_days_base_60 (summer cooling degree days base 60), …; 67 normals-fall fields (NOAA U.S. Climate Normals 1991–2020, annual and seasonal station normals, by county): fall_cooling_degree_days_base_40 (fall cooling degree days base 40), fall_cooling_degree_days_base_45 (fall cooling degree days base 45), fall_cooling_degree_days_base_50 (fall cooling degree days base 50), fall_cooling_degree_days_base_55 (fall cooling degree days base 55), fall_cooling_degree_days_base_57 (fall cooling degree days base 57), fall_cooling_degree_days_base_60 (fall cooling degree days base 60), …; 15 hourly fields (NOAA U.S. Climate Normals 1991–2020, hourly station normals summarised over the year, by county): hourly_temperature (round the clock temperature), dew_point (dew point), sea_level_pressure (sea level pressure), cooling_degree_hours (cooling degree hours), heating_degree_hours (heating degree hours), clear_sky_share (share of clear hours), …; 51 b01001 fields (U.S. Census Bureau, ACS 2020–2024 5-year estimates): pct_under_18 (share of residents aged 0 to 17), pct_5_to_14 (share of residents aged 5 to 14), b01001_001 (sex by age total), b01001_002 (sex by age male), b01001_003 (sex by age male 0 to 4 years), b01001_004 (sex by age male 5 to 9 years), …; 20 b11005 fields (U.S. Census Bureau, ACS 2020–2024 5-year estimates): pct_households_with_people_under_18 (share of households with people aged 0 to 17), b11005_001 (households by presence of people 0 to 17 years by household type total), b11005_002 (households by presence of people 0 to 17 years by household type households with people 0 to 17 years), b11005_003 (households by presence of people 0 to 17 years by household type households with people 0 to 17 years family households), b11005_004 (households by presence of people 0 to 17 years by household type households with people 0 to 17 years family households married-couple family), b11005_005 (households by presence of people 0 to 17 years by household type households with people 0 to 17 years family households other family), …; 3 b25003 fields (U.S. Census Bureau, ACS 2020–2024 5-year estimates): b25003_001 (tenure total), b25003_002 (tenure owner occupied), b25003_003 (tenure renter occupied); 13 b08303 fields (U.S. Census Bureau, ACS 2020–2024 5-year estimates): b08303_001 (travel time to work total), b08303_002 (travel time to work 0 to 4 minutes), b08303_003 (travel time to work 5 to 9 minutes), b08303_004 (travel time to work 10 to 14 minutes), b08303_005 (travel time to work 15 to 19 minutes), b08303_006 (travel time to work 20 to 24 minutes), …; 7 b23025 fields (U.S. Census Bureau, ACS 2020–2024 5-year estimates): b23025_001 (employment status for the population 16 years or older total), b23025_002 (employment status for the population 16 years or older in labor force), b23025_003 (employment status for the population 16 years or older in labor force civilian labor force), b23025_004 (employment status for the population 16 years or older in labor force civilian labor force employed), b23025_005 (employment status for the population 16 years or older in labor force civilian labor force unemployed), b23025_006 (employment status for the population 16 years or older in labor force armed forces), …; 30 buildings fields (Overture Maps buildings, release 2026-08-19.0, summed per area): buildings (buildings), multi_story_buildings (multi-story buildings), mid_rise_buildings (mid-rise buildings), high_rise_buildings (high-rise buildings), buildings_2_floors_plus (buildings with 2 published floors and up), buildings_4_floors_plus (buildings with 4 published floors and up), …; 13 building-types fields (Overture Maps buildings, release 2026-08-19.0, summed per area): residential_buildings (residential buildings), outbuilding_buildings (outbuilding buildings), commercial_buildings (commercial buildings), industrial_buildings (industrial buildings), education_buildings (education buildings), agricultural_buildings (agricultural buildings), …; 43 building-classes fields (Overture Maps buildings, release 2026-08-19.0, summed per area): house_class_buildings (house class buildings), detached_class_buildings (detached class buildings), residential_class_buildings (residential class buildings), garage_class_buildings (garage class buildings), apartments_class_buildings (apartments class buildings), shed_class_buildings (shed class buildings), …; 42 building-classes-2 fields (Overture Maps buildings, release 2026-08-19.0, summed per area): religious_class_buildings (religious class buildings), civic_class_buildings (civic class buildings), fire_station_class_buildings (fire station class buildings), bungalow_class_buildings (bungalow class buildings), pavilion_class_buildings (pavilion class buildings), hut_class_buildings (hut class buildings), …; 27 building-roofs fields (Overture Maps buildings, release 2026-08-19.0, summed per area): gabled_roof_buildings (buildings with a gabled roof), flat_roof_buildings (buildings with a flat roof), hipped_roof_buildings (buildings with a hipped roof), mansard_roof_buildings (buildings with a mansard roof), round_roof_buildings (buildings with a round roof), pyramidal_roof_buildings (buildings with a pyramidal roof), …; 11 building-facades fields (Overture Maps buildings, release 2026-08-19.0, summed per area): brick_facade_buildings (buildings with a brick facade), wood_facade_buildings (buildings with a wood facade), metal_facade_buildings (buildings with a metal facade), concrete_facade_buildings (buildings with a concrete facade), plaster_facade_buildings (buildings with a plaster facade), plastic_facade_buildings (buildings with a plastic facade), …. | |
| area_columns | No | Census and NOAA 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. Free. The same attribute words area_where takes (listed there). |