API overview
Base URL, request format, response headers and conventions shared by every Verify endpoint.
Base URL
https://api.fieldgeist.comAll endpoints are served over HTTPS.
Endpoints
| Method | Path | Does |
|---|---|---|
POST | /v1/verify/parse | Free text to USPS-standard components |
POST | /v1/verify/lookup | Parsed address to parcel |
GET | /v1/verify/lookup/{fieldgeist_id} | One parcel by its Fieldgeist ID |
Only answers with HTTP status 200 are billed. See Credits and billing, and the pricing page for rates.
Requests
- Authentication:
Authorization: Bearer <key>on every request. See Authentication. - Bodies:
POSTendpoints take a JSON body. SendContent-Type: application/json. - Responses: JSON, including every error from these endpoints. Errors share one shape:
{ "error": "location_required", "message": "zip5, city+state, or a city whose name is in only one state" }error is a stable, machine-readable code; branch on it. message is for people and may change. Some errors add fields, such as max on line_too_long. See Errors.
Response headers
| Header | On | Meaning |
|---|---|---|
x-request-id | Every request made with a valid key | The request's ID (req_ followed by 26 characters). The same ID appears on the request's row in the portal's Logs. Include it when you contact support. |
Server-Timing | Successful answers | Where the time went on our side, such as inference;dur=… for parse and r2fetch;dur=…, match;dur=… and total;dur=… for lookups. For diagnostics only: the metric names can change. |
WWW-Authenticate | 401 responses | Bearer. |
Paths and versions
The version is in the path (/v1). Fieldgeist gives at least 30 days' notice by email before retiring an API that teams are using (see the Terms).
Two older paths are still served and behave exactly like the current ones. Use the /v1/verify/... paths in new code.
| Older path | Current path |
|---|---|
POST /v1/address/parse | POST /v1/verify/parse |
POST /v1/property/lookup | POST /v1/verify/lookup |
GET /v1/property/lookup/{fieldgeist_id} | GET /v1/verify/lookup/{fieldgeist_id} |
Calling from a browser
The API is meant to be called from your servers. It doesn't send CORS headers for your origins, so browser code on your site can't call it directly, and a key in browser code would be public anyway.
Data conventions
- Address components are uppercase strings, as USPS Publication 28 writes them (
"AVE","NW","APT"). - Component keys are camelCase (
addressNumber,zip5). Parcel identifiers are snake_case (fieldgeist_id,building_id). - Fields that have no value are
nullin lookup responses and are left out of parsecomponents. - Coordinates are decimal degrees (
lat,lon).