LocationLists

Buy an ENTIRE dataset outright and get a permanent download link for the CSV. Pays once in USDC on Base, 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.

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).

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"}.

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 or drive_minutes 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 60 minutes by road of these three offices" is by=metro with near={points:[…], drive_minutes:60}. Drive time on this server: 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. Radius is free everywhere; on /find, drive_minutes needs an issued key and the answer offers the radius link instead. Drive time depends on an outside routing service: when an answer says drive-time search is un…

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 list…

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.

For buyers paying by card (no wallet needed): 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. Agents with a USDC wallet 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).

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.

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.

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.

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} or {place: "Richmond, VA", drive_minutes: 30} 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.

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 or drive_minutes) 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 in USDC via x402 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 an x402 PaymentRequired quote 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…

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…

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.

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.

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.