{"openapi":"3.1.0","info":{"title":"LocationLists","version":"1.2.0","summary":"US business location lists, from a web link: locationlists.com/find?q=your question","description":"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.\n\nBusiness location data for AI agents. Search, sample, count and buy ready-to-use lists of US business locations: 1,084 datasets compiled from each brand's official store locator or the public register that publishes the data.\n\n- Healthcare (257): every NPPES provider, Medicare-enrolled clinicians, nurse practitioners, pharmacists\n- Retail chains (178): Target, CVS, Walgreens, Aldi, Publix, Taco Bell\n- Federal contractors (148): every active SAM.gov registration, grant recipients\n- Industrial and equipment rental (99): Grainger, Fastenal, United Rentals, Sunbelt Rentals, Herc\n- Nonprofits (90): the full IRS file, grants awarded, churches\n- Bank branches (87): every FDIC-insured office\n- Equipment and tool dealers (40): STIHL, Husqvarna, DeWalt, Milwaukee, Makita\n- Furniture and mattresses (27): Ashley, Rooms To Go, Pottery Barn, Mattress Firm, Sleep Number\n- Restaurants (17): Dunkin', Waffle House, IHOP, Cracker Barrel\n- Hardware (14): Home Depot, Lowe's, Ace Hardware, Do It Best\n- Grill dealers (9): Traeger, Weber, Big Green Egg\n\nFilter by city, state, zip, a radius around any place, or any column in the file. Free tools search the catalog, show 10 real rows and count matches. Buy a full CSV by card, or let an agent pay per row or buy the whole file in USDC on Base via x402, with no account or API key. A failed or empty query costs nothing.","contact":{"url":"https://locationlists.com/contact"},"license":{"name":"LocationLists commercial license","url":"https://locationlists.com/license"}},"servers":[{"url":"https://locationlists.com"}],"externalDocs":{"url":"https://locationlists.com/agents","description":"Agent setup and payment flow"},"paths":{"/catalog.json":{"get":{"summary":"Full catalog","description":"Every dataset with record count, fields, coverage, price and links.","security":[],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/data/{slug}/dataset.json":{"get":{"summary":"One dataset record","description":"Fields, counts, coverage, price and the file's real last-modified date.","security":[],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"dental-practice-list","description":"Dataset slug from /catalog.json"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Unknown dataset","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/data/{slug}/sample.json":{"get":{"summary":"Ten real sample rows","description":"Ten rows from the live file plus the dataset record. No signup.","security":[],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"dental-practice-list","description":"Dataset slug from /catalog.json"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Unknown dataset","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/x402/query":{"post":{"operationId":"queryLocations","summary":"Query a location dataset (paid per row, x402)","description":"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.\n\nReady-to-use lists of US business locations: 1,084 datasets compiled from each brand's official store locator or the public register that publishes the data. Filter by city, state, zip, a radius around any place, or any column. Same arguments as the MCP tool query_locations: one dataset, or several datasets / a category plus total combined into one answer, one payment and one file with a source_dataset column (e.g. {\"category\":\"retail\",\"near\":{\"place\":\"Los Angeles, CA\",\"radius_miles\":25},\"total\":10}). An unpaid request returns 402 with the exact price in the PAYMENT-REQUIRED header; retry with PAYMENT-SIGNATURE. Settled only when rows are delivered. Use the free MCP tool count_locations at https://locationlists.com/mcp to see match counts and cost first.","security":[],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0.02","max":"8.55"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset slug, e.g. nonprofits-va. To combine several, give datasets or category instead."},"state":{"type":"string","description":"Shortcut for where state eq <value>. Two-letter code."},"city":{"type":"string","description":"Shortcut for where city eq <value>"},"county":{"type":"string","description":"Shortcut for where county eq <value>"},"zip":{"type":"string","description":"Shortcut for where zip eq <value>"},"where":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"Column name as listed by get_dataset (columns[].name), e.g. revenue_amt"},"op":{"type":"string","enum":["eq","ne","gt","gte","lt","lte","in","contains","starts_with","is_blank","not_blank"],"description":"eq/ne: case-insensitive match (numeric when both sides are numbers; yes/no, true/false, y/n and 1/0 count as the same answer). gt/gte/lt/lte: numeric when value is a number, else text order (works for ISO dates). in: value is an array. contains/starts_with: case-insensitive text. is_blank/not_blank: no value."},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":["string","number"]}}]}},"required":["field","op"],"additionalProperties":false},"maxItems":12,"description":"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."},"near":{"type":"object","properties":{"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 in that state, and the answer says which."},"zip":{"type":"string","description":"5-digit zip, e.g. \"66603\""},"lat":{"type":"number"},"lng":{"type":"number"},"radius_miles":{"type":"number","exclusiveMinimum":0,"maximum":500,"description":"Only rows within this straight-line distance"},"drive_minutes":{"type":"integer","minimum":5,"maximum":60,"description":"Instead of radius_miles: only rows within this many minutes' drive (typical road speeds, no live traffic)"}},"additionalProperties":false,"description":"Distance search, on lists with map coordinates (distanceSearch in search results): give ONE of place, zip, or lat+lng. 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). Give radius_miles or drive_minutes, not both. Rows without coordinates are excluded and counted."},"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: 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; 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), …."},"area_columns":{"type":"array","items":{"type":"string"},"maxItems":6,"description":"Census facts added to every row as columns named <kind>_<attribute>, each as \"<kind>:<attribute>,<attribute>\", e.g. \"county:population,median_household_income\". Free."},"datasets":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":150,"description":"Instead of dataset: several dataset slugs answered as one (one count, one preview, one price, one file)"},"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)"},"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)"},"total":{"type":"integer","minimum":1,"maximum":1000,"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"},"relate":{"type":"object","additionalProperties":{}},"order_by":{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string","enum":["asc","desc"],"description":"Default desc"}},"required":["field"],"additionalProperties":false,"description":"Return the top rows by one column, e.g. {field: 'revenue_amt'} for the largest first. Blanks sort last."},"offset":{"type":"integer","minimum":0,"maximum":10000,"description":"Skip this many matching rows, to page past the first call"},"limit":{"type":"integer","minimum":1,"maximum":1000,"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."}},"additionalProperties":false},"example":{"dataset":"dental-practice-list","state":"TX","city":"Austin","limit":10}}}},"responses":{"200":{"description":"Matching rows. PAYMENT-RESPONSE carries the settlement receipt.","headers":{"PAYMENT-RESPONSE":{"schema":{"type":"string"},"description":"base64 JSON SettlementResponse"}},"content":{"application/json":{"schema":{"type":"object","properties":{"dataset":{"type":"string"},"filters":{"type":"array","items":{"type":"string"}},"matched":{"type":"integer","description":"Rows matching the filters across the whole file"},"offset":{"type":"integer"},"returned":{"type":"integer","description":"Rows in this response (never more than limit)"},"truncated":{"type":"boolean","description":"True when more rows matched; page with offset"},"excludedBlank":{"type":"object","additionalProperties":{"type":"integer"}},"blankNote":{"type":["string","null"]},"columns":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"type":"object","additionalProperties":{"type":"string"}}},"csv":{"type":"string"},"note":{"type":"string"}},"required":["dataset","matched","returned","columns","rows"]},"example":{"dataset":"US Dental Practices","filters":["state eq AK","city eq Kodiak"],"matched":1,"offset":0,"returned":1,"truncated":false,"excludedBlank":{},"blankNote":null,"columns":["name","facilityType","subType","npisAtAddress","npi","address","city","state","zip","country","phone","certifiedDate","chainName","sourceUrl","latitude","longitude","geo_precision","county","county_fips","county_note","address_quality"],"rows":[{"name":"\"Gentle Dentistry\" Jennifer Spivey Dds","facilityType":"dental practice","subType":"general dentistry","npisAtAddress":"1","npi":"1306273446","address":"204 Rezanof Dr E, Suite #201","city":"Kodiak","state":"AK","zip":"99615-6379","country":"US","phone":"9074813567","certifiedDate":"2013-10-03","chainName":"","sourceUrl":"https://npiregistry.cms.hhs.gov/api/"}],"note":"All matching rows returned."}}}},"400":{"description":"Invalid body, unknown dataset or column, or dataset not sold by the row. Free.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Payment Required. Terms in the PAYMENT-REQUIRED header (base64 JSON) and the body.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"base64 JSON PaymentRequired"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}}}}