# LocationLists Query API

> LocationLists Query API is a paid API for AI agents from locationlists.com, paid per call via x402, $0.04/call, status unknown (last checked 2026-09-19).

Search, filter, count, and retrieve US business location records from 960 brand datasets, with per-row or full-file purchase via USDC on Base (x402) or card.

## Facts

- Endpoint: POST https://locationlists.com/api/x402/query
- Price: $0.04/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-19
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/locationlists-query-api-3fb29a22
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_pHUsKllhn7qWPsj79R0Md

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability locationlists-query-api-3fb29a22 -d '<json body>'
```

Example prompt: Pull me up to 50 Walgreens pharmacy locations in the state of Illinois from LocationLists — I want the name, address, city, zip, and phone number for each one.

## When to prefer this

Choose this endpoint when you need structured, ready-to-use US business location data from a specific brand or category — especially when you want to filter by geography (city, state, zip, radius, drive time) or custom column values without building a scraper. It excels for retail competitor analysis, healthcare facility lookup, franchise mapping, and local business prospecting. Prefer it over general web search when you need clean, CSV-grade structured records with address and phone data, and when agent-native micropayment via x402/USDC on Base is desirable over API-key account setup.

## Known failure modes

- Empty result set (matched=0) if no locations match the filters — costs nothing
- Dataset not found if an invalid dataset name is supplied
- Radius too large if radius_miles exceeds 500
- Too many where clauses if more than 12 filter conditions are provided
- Payment failure if USDC balance is insufficient on Base
- Invalid field name in where clause or order_by returns an error
- Drive-minutes out of range if drive_minutes is below 5 or above 60

## How this service works

Business location data for AI agents. Search, sample, count and buy ready-to-use lists of US business locations: 966 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 in the file. 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.

## Output

A JSON object containing matched rows of business location data (name, address, city, state, zip, phone, facility type, chain name, and dataset-specific columns), plus metadata: total matched count, returned count, offset, column list, applied filters, dataset name, and a truncated flag indicating whether more rows exist beyond the limit.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "zip": {
   "type": "string"
  },
  "city": {
   "type": "string"
  },
  "near": {
   "type": "object",
   "properties": {
    "lat": {
     "type": "number"
    },
    "lng": {
     "type": "number"
    },
    "zip": {
     "type": "string"
    },
    "place": {
     "type": "string"
    },
    "radius_miles": {
     "type": "number",
     "maximum": 500,
     "exclusiveMinimum": 0
    },
    "drive_minutes": {
     "type": "integer",
     "maximum": 60,
     "minimum": 5
    }
   },
   "additionalProperties": false
  },
  "limit": {
   "type": "integer",
   "maximum": 1000,
   "minimum": 1
  },
  "state": {
   "type": "string"
  },
  "total": {
   "type": "integer",
   "maximum": 1000,
   "minimum": 1
  },
  "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"
      ],
      "type": "string"
     },
     "field": {
      "type": "string"
     },
     "value": {
      "anyOf": [
       {
        "type": "string"
       },
       {
        "type": "number"
       },
       {
        "type": "boolean"
       },
       {
        "type": "array",
        "items": {
         "type": [
          "string",
          "number"
         ]
        }
       }
      ]
     }
    },
    "additionalProperties": false
   },
   "maxItems": 12
  },
  "county": {
   "type": "string"
  },
  "offset": {
   "type": "integer",
   "maximum": 10000,
   "minimum": 0
  },
  "relate": {
   "type": "object",
   "additionalProperties": {}
  },
  "dataset": {
   "type": "string"
  },
  "exclude": {
   "type": "array",
   "items": {
    "type": "string"
   }
  },
  "category": {
   "type": "string"
  },
  "datasets": {
   "type": "array",
   "items": {
    "type": "string"
   },
   "maxItems": 150,
   "minItems": 1
  },
  "order_by": {
   "type": "object",
   "required": [
    "field"
   ],
   "properties": {
    "field": {
     "type": "string"
    },
    "direction": {
     "enum": [
      "asc",
      "desc"
     ],
     "type": "string"
    }
   },
   "additionalProperties": false
  },
  "area_where": {
   "type": "array",
   "items": {
    "type": "string"
   },
   "maxItems": 6
  },
  "area_columns": {
   "type": "array",
   "items": {
    "type": "string"
   },

… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "note": "All matching rows returned.",
  "rows": [
   {
    "npi": "1306273446",
    "zip": "99615-6379",
    "city": "Kodiak",
    "name": "\"Gentle Dentistry\" Jennifer Spivey Dds",
    "phone": "9074813567",
    "state": "AK",
    "address": "204 Rezanof Dr E, Suite #201",
    "country": "US",
    "subType": "general dentistry",
    "chainName": "",
    "sourceUrl": "https://npiregistry.cms.hhs.gov/api/",
    "facilityType": "dental practice",
    "certifiedDate": "2013-10-03",
    "npisAtAddress": "1"
   }
  ],
  "offset": 0,
  "columns": [
   "name",
   "facilityType",
   "subType",
   "npisAtAddress",
   "npi",
   "address",
   "city",
   "state",
   "zip",
   "country",
   "phone",
   "certifiedDate",
   "chainName",
   "sourceUrl"
  ],
  "dataset": "US Dental Practices",
  "filters": [
   "state eq TX",
   "city eq Austin"
  ],
  "matched": 1,
  "returned": 1,
  "blankNote": null,
  "truncated": false,
  "excludedBlank": {}
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/locationlists-query-api-3fb29a22/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from locationlists.com](https://www.zero.xyz/host/locationlists.com/llms.txt)