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, 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 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.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "count_locations"
}
}Input 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' or radius_miles for 'everything within 25 miles'. Drive time is not offered. Rows without coordinates are excluded and counted. | |
| 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; several states comma-separated ("VA,NC,SC") are one `in`. | |
| 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), …; 191 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), …; 6 zillow fields (Zillow Home Value Index (ZHVI), all homes, middle tier, smoothed and seasonally adjusted, September 2026): typical_home_value (typical home value), home_value_change_1_year (one-year home value change), home_value_change_5_years (five-year home value change), typical_rent (typical monthly rent), rent_change_1_year (one-year rent change), price_to_rent_ratio (price-to-rent ratio); 11 permits fields (U.S. Census Bureau, Building Permits Survey, county files: calendar 2025 and September 2025–August 2026): housing_units_permitted_2025 (housing units permitted in 2025), single_family_units_permitted_2025 (single-family homes permitted in 2025), multifamily_units_permitted_2025 (multifamily units permitted in 2025), residential_buildings_permitted_2025 (residential buildings permitted in 2025), permitted_construction_value_2025 (construction value of housing permitted in 2025), housing_units_permitted_last_12_months (housing units permitted), …; 55 irs fields (IRS Statistics of Income, individual income tax returns by ZIP code and county, tax year 2022): tax_returns (tax returns filed), people_on_tax_returns (people on tax returns), total_adjusted_gross_income (total adjusted gross income), average_adjusted_gross_income (average adjusted gross income), income_per_person (adjusted gross income for each person), average_wages (average wages and salaries), …; 455 fema nri fields (FEMA National Risk Index, December 2025 release, by county): risk_index_population (national risk index population), building_value (building value), agriculture_value (agriculture value), land_area (land area), national_risk_index_value (national risk index value), national_risk_index_score (national risk index score), …; 3352 usda ag census fields (USDA Census of Agriculture 2022, by county): animal_totals_including_products_operations_with_sales (animal totals including products operations with sales), livestock_sales (livestock and animal product sales), animal_totals_including_products_sales_percent_of_farm_operations (animal totals including products sales percent of farm operations), animal_totals_including_products_sales_percent_of_farm_sales (animal totals including products sales percent of farm sales), animals_other_production_contract_operations_with_production (animals other production contract operations with production), aquaculture_totals_operations_with_sales_and_distribution (aquaculture totals operations with sales and distribution), …. | |
| area_columns | No | 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). |