# Places & Local Business Search

**Places & Local Business Search** is an independently documented x402 Atlas bridge at https://places.use.x402atlas.com.
This document describes only this bridge; it does not aggregate routes, schemas,
or content from any other bridge.

## How payment works

Paid operations use the [x402 payment protocol](https://x402.org) and settle in
USDC. Atlas supports deployments on Base, Polygon, and Arbitrum, plus configured
Solana networks. This bridge currently advertises Arbitrum One (`eip155:42161`), Base (`eip155:8453`), Polygon (`eip155:137`), Solana mainnet (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`).

1. Send the HTTP request without a payment signature.
2. Read the `402 Payment Required` response. Its `accepts` entries are the
   authoritative network, asset, amount, and recipient options for that call.
3. Select an option, sign it with an x402-compatible wallet or SDK, and repeat
   the request with the `PAYMENT-SIGNATURE` header. The successful response is
   returned after verification and settlement.

TypeScript clients can automate the challenge, signing, and retry flow with
[`x402-fetch`](https://www.npmjs.com/package/x402-fetch) or
[`x402-axios`](https://www.npmjs.com/package/x402-axios). Fund a dedicated
wallet only with the working USDC balance it needs and keep that key separate
from treasury accounts.

## Pricing

Atlas route prices start at $0.005 per successful call. This bridge's fallback
price is $0.005; operations below state their exact configured price in
`x-x402` and `x-payment-info`. The live `402` challenge remains authoritative.

## Worked payment example

Request one documented operation without a signature to inspect its live terms:

```bash
curl -i 'https://places.use.x402atlas.com/apple/local?center=37.7749%2C-122.4194&q=coffee&span=0.05%2C0.05'
# HTTP/1.1 402 Payment Required
# Read accepts[].network, asset, amount, and payTo from this response.
```

Sign one accepted option and repeat the identical request with the
`PAYMENT-SIGNATURE` header. Do not invent or cache payment terms; read them from
the current challenge.

## Use this API

- Interactive reference: https://places.use.x402atlas.com/docs
- OpenAPI 3.1 specification: https://places.use.x402atlas.com/openapi.json
- Agent-readable route corpus: https://places.use.x402atlas.com/llms.txt
- Endpoint index: https://places.use.x402atlas.com/index.json

Use the operation schemas and examples below to construct requests. Copy the
server URL, path, method, parameters, and request body from the operation you
want to call. Path and query examples are concrete and can be used directly.

## Atlas response metadata

Successful JSON responses include an additive top-level `_atlas` block, kept
separate from the bridge's data fields. `_atlas.docs` links this bridge's
`/llms.txt` corpus. `_atlas.related` suggests adjacent APIs, each with a callable
`url`, its own `docs` link, and a short `summary`. Suppress this block by sending
`X-Atlas-Meta: none` or by adding `?_atlas=0` to the request.

## Errors and compatibility

Validation failures use HTTP `400`. Paid operations may return `402` before
dispatch. Upstream and internal failures use the documented `5xx` responses.
Clients should rely on documented fields and tolerate additive response fields,
including `_atlas` unless they explicitly opt out.

## Protocol reference

- x402 protocol and SDKs: https://x402.org

## Places & Local Business Search

Docs: https://places.use.x402atlas.com/docs · OpenAPI: https://places.use.x402atlas.com/openapi.json

### GET /apple/local

Apple Maps local business search — find places by query and map centre (latitude,longitude), returning ratings, reviews, address, phone, website & Apple Maps place ids (muid) as clean JSON.

Apple Maps local business search: pass a `q` query (required, e.g. "coffee") and an optional `center` viewport as `latitude,longitude` (e.g. `37.7749,-122.4194`) plus an optional `span` (`lat_span,lng_span`). Returns Apple Maps places as `{ query, queried_at, results }`, where each result carries `title`, `muid` (Apple's place id — pass it to `/apple/place`), `place_id`, `gps_coordinates`, `rating`, `max_rating`, `reviews`, `types`, `address`, `phone`, `website`, `open_state` and `weekly_hours`. For Google Maps data use `/local`; for a place name search use `/search`. A query with no matches returns `404 not_found`.

**Price:** $0.02 per call.

Parameters:
- `center` (optional, string) — Optional viewport centre as latitude,longitude (e.g. 37.7749,-122.4194); maxLength: `32`; example: `"37.7749,-122.4194"`
- `q` (required, string) — Apple Maps search query (business or category); maxLength: `400`; example: `"coffee"`
- `span` (optional, string) — Optional viewport span as lat_span,lng_span (e.g. 0.05,0.05); maxLength: `32`; example: `"0.05,0.05"`

Example:

```sh
curl 'https://places.use.x402atlas.com/apple/local?center=37.7749%2C-122.4194&q=coffee&span=0.05%2C0.05'
```

Response example:

```json
{
  "queried_at": "2026-07-11T12:00:00Z",
  "query": "coffee",
  "results": [
    {
      "address": "1 Ferry Building, San Francisco, CA",
      "muid": "1234567890",
      "position": 1,
      "rating": 4.5,
      "reviews": 812,
      "title": "Blue Bottle Coffee",
      "types": [
        "Coffee shop"
      ]
    }
  ]
}
```

### GET /apple/place

Apple Maps place details — full profile for a single Apple Maps place (muid): ratings, reviews, weekly hours, phone, website, categories & address as clean JSON.

Apple Maps place details: pass a `muid` (required — Apple's place id from `/apple/local`) to pull the full profile for one place. Returns `{ queried_at, place }`, where `place` carries `title`, `muid`, `gps_coordinates`, `rating`, `max_rating`, `reviews`, `type`, `types`, `address`, `phone`, `website`, `open_state` and `weekly_hours`. An unknown identifier returns `404 not_found`.

**Price:** $0.02 per call.

Parameters:
- `muid` (required, string) — Apple Maps place id (muid, from /places/apple/local results); maxLength: `512`; example: `"6435622567484707146"`

Example:

```sh
curl 'https://places.use.x402atlas.com/apple/place?muid=6435622567484707146'
```

Response example:

```json
{
  "place": {
    "address": "270 7th St, San Francisco, CA",
    "muid": "6435622567484707146",
    "rating": 4.5,
    "reviews": 812,
    "title": "Sightglass Coffee",
    "type": "Coffee shop",
    "website": "https://sightglasscoffee.com"
  },
  "queried_at": "2026-07-11T12:00:00Z"
}
```

### GET /ddg/local

DuckDuckGo Maps local business search (Apple Maps + Tripadvisor data) — find places by query and location, returning ratings, reviews, address, phone, website & hours as clean JSON.

DuckDuckGo Maps local business search (Apple Maps + Tripadvisor data): pass a `q` query (required, e.g. "coffee") and an optional location as `lat`+`lon` (both together) or a `bbox` (`lat_tl,lng_tl,lat_br,lng_br`). Returns `{ query, queried_at, results }`, where each result carries `title`, `gps_coordinates`, `rating`, `reviews`, `type`, `types`, `address`, `phone`, `website`, `hours` and `price`. DuckDuckGo Maps is search-only — there is no place-details route; for that use `/place` (Google) or `/apple/place` (Apple). A query with no matches returns `404 not_found`.

**Price:** $0.02 per call.

Parameters:
- `bbox` (optional, string) — Bounding box as lat_tl,lng_tl,lat_br,lng_br; maxLength: `96`
- `lat` (optional, string) — Latitude (must be paired with lon); maxLength: `32`
- `lon` (optional, string) — Longitude (must be paired with lat); maxLength: `32`
- `q` (required, string) — DuckDuckGo Maps search query (business or category); maxLength: `400`; example: `"coffee"`

Example:

```sh
curl 'https://places.use.x402atlas.com/ddg/local?q=coffee'
```

Response example:

```json
{
  "queried_at": "2026-07-11T12:00:00Z",
  "query": "coffee",
  "results": [
    {
      "address": "1 Ferry Building, San Francisco, CA",
      "position": 1,
      "rating": 4.5,
      "reviews": 812,
      "title": "Blue Bottle Coffee",
      "type": "Coffee shop"
    }
  ]
}
```

### GET /local

Google Maps local business search — find places by query and map location (coordinates viewport), returning ratings, reviews, address, phone, website, hours & service options as clean JSON.

Google Maps local business search: pass a `q` query (required, e.g. "coffee" or "plumber near me") and an optional `ll` viewport (`@latitude,longitude,zoom`, e.g. `@40.7455,-74.0083,14z`) to bias results to an area. Returns `{ query, queried_at, results }`, where each result is a place with `title`, `place_id`, `data_id`, `gps_coordinates`, `rating`, `reviews`, `type`, `address`, `phone`, `website`, `price`, `hours`, `open_state` and `service_options`. Use `place_id`/`data_id` with `/place` to pull the full profile for one result. To search by a free-text place name instead of coordinates, use `/search`. Optional `hl` (language) and `gl` (country) localize the response. A query with no matches returns `200` with an empty `results` list.

**Price:** $0.02 per call.

Parameters:
- `gl` (optional, string) — Optional country code (e.g. us); maxLength: `8`; example: `"us"`
- `hl` (optional, string) — Optional language code (e.g. en); maxLength: `8`; example: `"en"`
- `ll` (optional, string) — Optional viewport to bias results: @latitude,longitude,zoom (e.g. @40.7455,-74.0083,14z); maxLength: `64`; example: `"@40.7455096,-74.0083012,14z"`
- `q` (required, string) — Google Maps search query (business, category, or 'near me' phrase); maxLength: `400`; example: `"coffee"`

Example:

```sh
curl 'https://places.use.x402atlas.com/local?gl=us&hl=en&ll=%4040.7455096%2C-74.0083012%2C14z&q=coffee'
```

Response example:

```json
{
  "queried_at": "2026-07-10T12:00:00Z",
  "query": "coffee",
  "results": [
    {
      "address": "1 Rockefeller Plaza, New York, NY",
      "gps_coordinates": {
        "latitude": 40.7443,
        "longitude": -74.0034
      },
      "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
      "position": 1,
      "rating": 4.5,
      "reviews": 812,
      "title": "Blue Bottle Coffee",
      "type": "Coffee shop"
    }
  ]
}
```

### GET /place

Google Maps place details — full profile for a single place_id: ratings, reviews, hours, phone, website, price, service options, popular times & plus code as clean JSON.

Google Maps place details: pass a `place_id` (required — the id returned by `/local`) to pull the full profile for one place. Returns `{ queried_at, place }`, where `place` carries `title`, `gps_coordinates`, `rating`, `reviews`, `type`, `address`, `phone`, `website`, `price`, `description`, `open_state`, `hours`, `service_options` (dine-in/takeout/delivery), `popular_times` and `plus_code`. Optional `hl` (language) and `gl` (country) localize the response. An unknown `place_id` returns `404 not_found`.

**Price:** $0.02 per call.

Parameters:
- `gl` (optional, string) — Optional country code (e.g. us); maxLength: `8`; example: `"us"`
- `hl` (optional, string) — Optional language code (e.g. en); maxLength: `8`; example: `"en"`
- `place_id` (required, string) — Google Maps place id (from /places/local results); maxLength: `512`; example: `"ChIJN1t_tDeuEmsRUsoyG83frY4"`

Example:

```sh
curl 'https://places.use.x402atlas.com/place?gl=us&hl=en&place_id=ChIJN1t_tDeuEmsRUsoyG83frY4'
```

Response example:

```json
{
  "place": {
    "address": "1 Rockefeller Plaza, New York, NY",
    "gps_coordinates": {
      "latitude": 40.7443,
      "longitude": -74.0034
    },
    "phone": "+1 510-653-3394",
    "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
    "rating": 4.5,
    "reviews": 812,
    "title": "Blue Bottle Coffee",
    "type": "Coffee shop",
    "website": "https://bluebottlecoffee.com"
  },
  "queried_at": "2026-07-10T12:00:00Z"
}
```

### GET /search

Google Maps local business search by place name — find places by query and a free-text location (e.g. 'Austin, Texas'), no coordinates needed; returns Google's local-pack results as clean JSON.

Google Maps local business search by place name: pass a `q` query (required, e.g. "coffee" or "plumber") and an optional `location` as free text (e.g. "Austin, Texas, United States") — no latitude/longitude needed, so an agent doesn't have to geocode first. Returns Google's local-pack results as `{ query, queried_at, results }`, where each result is a place with `title`, `place_id`, `gps_coordinates`, `rating`, `reviews`, `type`, `address`, `hours`, `price` and `service_options`. Use `place_id` with `/place` to pull the full profile. Optional `hl` (language) and `gl` (country) localize the response. For a map-viewport search by coordinates use `/local` instead. A query with no matches returns `404 not_found`.

**Price:** $0.02 per call.

Parameters:
- `gl` (optional, string) — Optional country code (e.g. us); maxLength: `8`; example: `"us"`
- `hl` (optional, string) — Optional language code (e.g. en); maxLength: `8`; example: `"en"`
- `location` (optional, string) — Place to search in, as free text (e.g. 'Austin, Texas, United States') — no coordinates needed; maxLength: `200`; example: `"Austin, Texas, United States"`
- `q` (required, string) — Google Maps search query (business or category, e.g. 'coffee'); maxLength: `400`; example: `"coffee"`

Example:

```sh
curl 'https://places.use.x402atlas.com/search?gl=us&hl=en&location=Austin%2C+Texas%2C+United+States&q=coffee'
```

Response example:

```json
{
  "queried_at": "2026-07-10T12:00:00Z",
  "query": "coffee",
  "results": [
    {
      "address": "1 Rockefeller Plaza, New York, NY",
      "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
      "position": 1,
      "rating": 4.5,
      "reviews": 812,
      "title": "Blue Bottle Coffee",
      "type": "Coffee shop"
    }
  ]
}
```