GET
/v1/autocomplete
Get address suggestions
Returns ranked address suggestions for a partial query. Call it on every keystroke after the 2nd character.
Parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
q |
string | required | What the user has typed so far — part of a street address, a city name, or a ZIP prefix. Minimum 2 characters. | 1600 amph |
limit |
integer | optional | Maximum suggestions to return (1-20). Default is 8 — a good dropdown size. | 5 |
state |
string | optional | Two-letter state code (e.g. CA) to bias results toward that state. If omitted, we auto-detect the caller's state from their IP so nearby addresses rank first. | CA |
Code samples
# Keep the key in the environment, not in your shell history:
# export GEOVERIO_API_KEY="gv_live_…"
curl --fail-with-body "https://autocomplete.geoverio.com/v1/autocomplete?q=1600%20amph&limit=5&state=CA" \
-H "Authorization: Bearer $GEOVERIO_API_KEY"// Call this from your server, never from the browser:
// front-end JavaScript ships your key to every visitor.
const KEY = process.env.GEOVERIO_API_KEY;
async function main() {
const res = await fetch("https://autocomplete.geoverio.com/v1/autocomplete?q=1600%20amph&limit=5&state=CA", {
headers: {
Authorization: `Bearer ${KEY}`
}
});
// Never parse the body before checking the status: an expired key answers
// 401 with a perfectly valid JSON envelope.
if (!res.ok) {
throw new Error(`HTTP ${res.status} — ${await res.text()}`);
}
console.log(await res.json());
}
main().catch((err) => {
console.error(err);
process.exitCode = 1;
});# pip install requests
import os, requests
url = "https://autocomplete.geoverio.com/v1/autocomplete?q=1600%20amph&limit=5&state=CA"
headers = {"Authorization": "Bearer " + os.environ["GEOVERIO_API_KEY"]}
r = requests.get(url, headers=headers)
r.raise_for_status() # turns 4xx / 5xx into an exception instead of silent bad data
print(r.json())<?php
// Read the key from the server environment — never commit it.
$key = getenv('GEOVERIO_API_KEY');
$ch = curl_init("https://autocomplete.geoverio.com/v1/autocomplete?q=1600%20amph&limit=5&state=CA");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer $key",
"Accept: application/json",
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status < 200 || $status >= 300) {
fwrite(STDERR, "Request failed — HTTP $status: $body\n");
exit(1);
}
print_r(json_decode($body, true));See a sample response
{
"query": "1600 AMPH",
"count": 3,
"suggestions": [
{
"label": "1600 Amphitheatre Py, Mountain View, CA 94043",
"house": "1600",
"street": "Amphitheatre Py",
"city": "Mountain View",
"state": "CA",
"zip": "94043",
"lat": 37.4220221,
"lon": -122.0842902,
"tax_query": "1600 AMPHITHEATRE PY MOUNTAIN VIEW CA 94043"
},
{
"label": "1600 Amphitheatre Pkwy, Mountain View, CA 94043",
"house": "1600",
"street": "Amphitheatre Pkwy",
"city": "Mountain View",
"state": "CA",
"zip": "94043",
"lat": 37.4220018,
"lon": -122.0849364,
"tax_query": "1600 AMPHITHEATRE PKWY MOUNTAIN VIEW CA 94043"
},
{
"label": "1600 Amphitheatre Parkway, Mountain View, CA 94043",
"house": "1600",
"street": "Amphitheatre Parkway",
"city": "Mountain View",
"state": "CA",
"zip": "94043",
"lat": 37.4230075,
"lon": -122.0830662,
"tax_query": "1600 AMPHITHEATRE PARKWAY MOUNTAIN VIEW CA 94043"
}
]
}