Conventions
Base URL, authentication, errors and headers shared by every Fieldgeist API.
Base URL
https://api.fieldgeist.comAll endpoints are served over HTTPS.
Every Fieldgeist product is served from the same base URL, with the same keys, error shape and headers. This page covers what they share; each product's endpoints follow in the sidebar.
Endpoints
Verify
| 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, in milliseconds. Parse: tokenize, inference (model time), assemble and total. Lookups: match and total. For diagnostics only: the names can change. |
WWW-Authenticate | 401 responses | Bearer. |
Retry-After | 429 and 503 responses | Seconds to wait before retrying. |
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).
Each product's paths start with its name (/v1/verify/...).
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).