Local prototype · simulated data

Autocomplete API

Address suggestions and selection for authenticated keys.

GET /v1/autocomplete

Suggest US addresses for partial input

Local prototype · simulated data

Returns ranked suggestions for a partial street address. Publishable keys must be called from an allowed Origin.

Authentication

Authorization: Bearer <key> — a sk_test_… secret key from your server, or a pk_test_… publishable key from an allowed browser origin. See Authentication.

Parameters

Parameters
Name	In	Type	Required	Description
`q`	query	string	Yes	Partial address typed by the user. min length 2 · max length 100
`limit`	query	integer	No	min 1 · max 10 · default 5
`state`	query	string	No	Two-letter USPS state or territory code to restrict results. pattern `^[A-Za-z]{2}$`
`city`	query	string	No	max length 64
`zip`	query	string	No	ZIP code or prefix (1–5 digits). pattern `^[0-9]{1,5}$`

Responses

200 Suggestions (may be empty). — SuggestionList
400 Invalid parameters. — Error
401 Missing or invalid key. — Error
403 Key not allowed for this Origin or endpoint. — Error
429 Rate limit exceeded. — Error
500 Unexpected server error. — Error

Response fields (200)

Response fields
Field	Type	Required	Description
`data`	array of object	Yes	max 10 items
`data[].id`	string	Yes	pattern `^sug_[a-f0-9]{12}$`
`data[].label`	string	Yes
`data[].street_line`	string	Yes
`data[].secondary`	string \| null	Yes
`data[].city`	string	Yes
`data[].state`	string	Yes	min length 2 · max length 2
`data[].zip`	string	Yes	pattern `^[0-9]{5}$`
`data[].has_secondaries`	boolean	Yes
`data[].secondary_count`	integer	Yes	min 0
`meta`	object	Yes
`meta.request_id`	string	Yes
`meta.source`	enum: "simulated", "live"	Yes	`simulated` for mock data. `live` is reserved and is never produced by this version.
`meta.billable`	boolean	Yes	Always `false` in this version.

Example

cURL

curl "http://localhost:8787/v1/autocomplete?q=350+fifth&limit=3" \
  -H "Authorization: Bearer sk_test_PLACEHOLDER"

JavaScript

// Server-side (Node 18+). Never ship a secret key to a browser.
const res = await fetch("http://localhost:8787/v1/autocomplete?q=350+fifth&limit=3", {
  headers: { Authorization: "Bearer sk_test_PLACEHOLDER" },
});
const body = await res.json();
if (!res.ok) throw new Error(body.error.code);

Python

import requests

res = requests.get(
    "http://localhost:8787/v1/autocomplete",
    params={"q": "350 fifth", "limit": "3"},
    headers={"Authorization": "Bearer sk_test_PLACEHOLDER"},
    timeout=10,
)
res.raise_for_status()
print(res.json())

Response 200 from the local prototype (simulated data):

JSON

{
  "data": [
    {
      "id": "sug_de1d7b18927d",
      "label": "350 Fifth Ave, New York, NY 10118",
      "street_line": "350 Fifth Ave",
      "secondary": null,
      "city": "New York",
      "state": "NY",
      "zip": "10118",
      "has_secondaries": true,
      "secondary_count": 12
    }
  ],
  "meta": {
    "request_id": "req_0000000000000000docs",
    "source": "simulated",
    "billable": false
  }
}

GET /v1/addresses/{id}

Select a suggestion and get the full address

Local prototype · simulated data

Expands a suggestion. When the building has units, secondaries lists them so the user can pick one.

Authentication

Authorization: Bearer <key> — a sk_test_… secret key from your server, or a pk_test_… publishable key from an allowed browser origin. See Authentication.

Parameters

Parameters
Name	In	Type	Required	Description
`id`	path	string	Yes	Suggestion id from `/v1/autocomplete`. pattern `^sug_[a-f0-9]{12}$`
`secondary`	query	string	No	Filter units by a prefix, e.g. `4` or `Apt 4`. max length 20

Responses

200 The selected address. — AddressDetail
400 Invalid parameters. — Error
401 Missing or invalid key. — Error
403 Key not allowed for this Origin or endpoint. — Error
404 Resource not found. — Error
429 Rate limit exceeded. — Error

Response fields (200)

Response fields
Field	Type	Required	Description
`data`	object	Yes
`data.id`	string	Yes
`data.street_line`	string	Yes
`data.city`	string	Yes
`data.state`	string	Yes
`data.zip`	string	Yes
`data.secondaries`	array of string	Yes	Units in the building (empty when there are none).
`meta`	object	Yes
`meta.request_id`	string	Yes
`meta.source`	enum: "simulated", "live"	Yes	`simulated` for mock data. `live` is reserved and is never produced by this version.
`meta.billable`	boolean	Yes	Always `false` in this version.

Example

cURL

curl "http://localhost:8787/v1/addresses/sug_de1d7b18927d?secondary=suite+2" \
  -H "Authorization: Bearer sk_test_PLACEHOLDER"

JavaScript

// Server-side (Node 18+). Never ship a secret key to a browser.
const res = await fetch("http://localhost:8787/v1/addresses/sug_de1d7b18927d?secondary=suite+2", {
  headers: { Authorization: "Bearer sk_test_PLACEHOLDER" },
});
const body = await res.json();
if (!res.ok) throw new Error(body.error.code);

Python

import requests

res = requests.get(
    "http://localhost:8787/v1/addresses/sug_de1d7b18927d",
    params={"secondary": "suite 2"},
    headers={"Authorization": "Bearer sk_test_PLACEHOLDER"},
    timeout=10,
)
res.raise_for_status()
print(res.json())

Response 200 from the local prototype (simulated data):

JSON

{
  "data": {
    "id": "sug_de1d7b18927d",
    "street_line": "350 Fifth Ave",
    "city": "New York",
    "state": "NY",
    "zip": "10118",
    "secondaries": [
      "Suite 200",
      "Suite 2100"
    ]
  },
  "meta": {
    "request_id": "req_0000000000000000docs",
    "source": "simulated",
    "billable": false
  }
}