# Autocomplete addresses and places with PickPoint's Address Search API

PickPoint's Address Search API turns partial input, such as the first letters of a street or landmark, into ranked candidate places returned as a GeoJSON FeatureCollection. Each search is one request, billed at $0.25 per thousand requests and drawn from a plan held by your bearer credential. Send `GET https://agents.pickpoint.io/zcj/ykuqrfgtw630/v2/address/search?q=<text typed so far>&limit=3` with `Authorization: Bearer <token>`, and add `lat` and `lon` to rank places near a point first.

## At a glance

- **Endpoint:** `GET https://agents.pickpoint.io/zcj/ykuqrfgtw630/v2/address/search`, one search per request
- **Query:** `q` (required, partial or complete input), plus optional `limit`, `lat`, `lon`, `bbox`, `layer`, `lang` and `osm_tag`
- **Price:** $0.25 per thousand requests. Each call is one request, and each keystroke you send is one call.
- **Access:** `Authorization: Bearer <token>` for a credential that holds the Free trial or Pay as you go. There is no per-call payment and no upstream API key.
- **Response:** a GeoJSON FeatureCollection. `geometry.coordinates` is `[longitude, latitude]`.
- **Details for a known place:** `GET https://agents.pickpoint.io/zcj/ykuqrfgtw630/v2/address/lookup?osm_ids=...`, up to 50 ids per call
- **Full purchase flow:** [buyer skill](https://agents.pickpoint.io/zcj/ykuqrfgtw630/SKILL.md)

## Search as the input is typed

1. Hold a credential with a plan. A bearer credential is the agent identity the storefront issues, and registering one is free. With it, claim the Free trial, which grants $0.625 of credit once per human and needs the credential claimed with a verified email. Or buy Pay as you go credit at `POST https://agents.pickpoint.io/zcj/ykuqrfgtw630/plans/{planId}/purchase`, with the plan id taken from the catalog at `https://agents.pickpoint.io/zcj/ykuqrfgtw630/manifest.json`. The minimum is $0.01 on a wallet rail and $0.50 by card. The purchase answers with a 402, the price quote you pay and retry. You can pay it over x402 or MPP, the USDC wallet rails, or by card. The purchase completes only when you pay. To check what the credential already holds before buying:

   ```bash
   curl -s "https://agents.pickpoint.io/zcj/ykuqrfgtw630/agent/entitlements" \
     -H "Authorization: Bearer $ACCESS_TOKEN"
   ```

2. Send the text typed so far as `q`:

   ```bash
   curl -s "https://agents.pickpoint.io/zcj/ykuqrfgtw630/v2/address/search?q=Golden+Gate+Bri&limit=3" \
     -H "Authorization: Bearer $ACCESS_TOKEN"
   ```

   The response is a FeatureCollection of up to three candidates. This is the first one, trimmed:

   ```json
   {
     "type": "FeatureCollection",
     "features": [
       {
         "type": "Feature",
         "geometry": {"type": "Point", "coordinates": [-122.4783122744124, "…"]},
         "properties": {
           "name": "Golden Gate Bridge",
           "street": "Golden Gate Bridge",
           "county": "Marin",
           "state": "California",
           "postcode": "94965",
           "country": "United States",
           "countrycode": "US",
           "osm_id": 370672707,
           "osm_type": "W",
           "osm_key": "man_made",
           "osm_value": "bridge",
           "type": "house",
           "extent": [-122.4809672, "…"]
         }
       },
       "… 2 more"
     ]
   }
   ```

   This search drew $0.00025 from the plan's credit.

3. Read each candidate. `geometry.coordinates` is longitude first, then latitude. Geocoding returns `lat` and `lon` as named fields. `properties` holds `name`, `street`, `city` where one applies, `county`, `state`, `postcode`, `country`, `osm_id` and `osm_type` (`N`, `W` or `R`). `properties.type` is the layer, such as `house` or `street`. `extent` is `min_lon, min_lat, max_lon, max_lat`.

4. Confirm the candidate before using it. Candidates are ranked, and the first one is not guaranteed to be the place meant. Check `name`, `city`, `state` and `type` against the input and the task, then keep the match.

## Rank nearby places first

Add `lat` and `lon` to bias results toward a point:

```bash
curl -s "https://agents.pickpoint.io/zcj/ykuqrfgtw630/v2/address/search?q=Congress+Ave&limit=3&lat=30.2747&lon=-97.7404" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

This search returned two candidates. `limit` is the maximum number of candidates. The first candidate is a bridge in Austin, Texas. Its properties, trimmed:

```json
{"locality": "Auditorium Shores", "city": "Austin", "county": "Travis", "state": "TX", "postcode": "78767", "osm_id": 708605258, "osm_type": "W", "osm_value": "bridge", "type": "house"}
```

This search drew $0.00025 from the plan's credit.

## Narrow the candidates

| To do this | Set | Value |
| --- | --- | --- |
| Rank places near a point first | `lat` and `lon` | Decimal degrees, always sent together |
| Widen or tighten that bias | `zoom` | Map zoom level. Lower values spread the bias wider. |
| Weigh prominence against distance | `location_bias_scale` | `0.0` (prominence almost ignored) to `1.0` (prominence and distance weigh about equally) |
| Favour the visible map area | `bbox` | `minLon,minLat,maxLon,maxLat` |
| Keep one place type | `layer` | `house`, `street`, `locality`, `district`, `city`, `county`, `state` or `country` |
| Return names in a language | `lang` | A BCP 47 tag, such as `en` or `de` |
| Filter by OpenStreetMap tag | `osm_tag` | `key:value` to include, `!key:value` to exclude, `key` or `:value`, such as `tourism:museum` |
| Return fewer candidates | `limit` | An integer. The default is 10. |

## Get full details for a chosen place

Build the id from the candidate's `osm_type` and `osm_id`, such as `W370672707`, and look it up:

```bash
curl -s "https://agents.pickpoint.io/zcj/ykuqrfgtw630/v2/address/lookup?osm_ids=W370672707&addressdetails=1" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

The response is an array with one entry per id found. Each entry has `lat` and `lon` as strings, `display_name`, an `address` breakdown, `place_rank` and `importance`. You can send up to 50 comma-separated ids in one call, and each call is one request. Set `extratags=1`, `namedetails=1` or one `polygon_` option for more detail.

## Limits

- `bbox`, `lat` and `lon` bias the ranking. `layer` and `osm_tag` filter the candidates.
- One query per search request. There is no batch search.
- Every call draws on a plan. A call without a credential is refused before it is served.
- Data from OpenStreetMap contributors is under the ODbL and needs attribution when displayed.

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `401 bearer_required` | No agent credential was sent | Register at [auth.md](https://agents.pickpoint.io/zcj/ykuqrfgtw630/auth.md) and retry with `Authorization: Bearer <token>` |
| `401 invalid_token` | The token did not verify, for example because it expired | Exchange the stored assertion for a fresh token and retry |
| `403 plan_required` | No plan covers the call | Buy one of the plans the body lists, then retry |
| `403 verified_email_required` | The Free trial needs a credential claimed with a verified email | Complete the claim step, or buy Pay as you go |
| `usage_exhausted` | The plan's credit ran out | Top up with `POST https://agents.pickpoint.io/zcj/ykuqrfgtw630/extend` and `{"amountUsd": "..."}` |

## Frequently asked questions

### Does the address search API return latitude or longitude first?

Longitude first. `geometry.coordinates` in each feature is `[longitude, latitude]`, following GeoJSON. Geocoding and lookup instead return `lat` and `lon` as named string fields.

### How much does address autocomplete cost per keystroke?

Each keystroke you send is one request at $0.25 per thousand requests. Searching a 15-character input on every keystroke is 15 requests, or $0.00375. A thousand searches cost $0.25.

### Can I limit address search results to one city or map area?

Pass the visible map area as `bbox`, or a point as `lat` and `lon`, to bias the ranking toward places there. To filter, set `layer` to keep one place type or `osm_tag` to keep places with a given OpenStreetMap tag.

### Does PickPoint's address search need an API key?

No upstream API key is needed. Each call carries a bearer credential that holds the Free trial or Pay as you go. Registering the credential is free, and the [buyer skill](https://agents.pickpoint.io/zcj/ykuqrfgtw630/SKILL.md) has the steps.

### Can I store the places that address search returns?

Yes. Results may be stored indefinitely. When you display them, attribute the OpenStreetMap contributors' data, which is licensed under the ODbL.

## Keep reading

- [Buyer skill](https://agents.pickpoint.io/zcj/ykuqrfgtw630/SKILL.md): the full purchase flow
- [Identity](https://agents.pickpoint.io/zcj/ykuqrfgtw630/auth.md): register and claim a credential
- [How to pay](https://agents.pickpoint.io/zcj/ykuqrfgtw630/payment.md): plans, rails and top-ups
- [Address Search API reference](https://agents.pickpoint.io/zcj/ykuqrfgtw630/services/address-search/openapi.json): every parameter and field
- [Error reference](https://agents.pickpoint.io/zcj/ykuqrfgtw630/errors.md): every error code

---

Updated 2026-11-06. All PickPoint guides: https://agents.pickpoint.io/guides.md. Storefront: https://agents.pickpoint.io/zcj/ykuqrfgtw630/llms.txt.