# Conventions (/api-reference)

## Base URL [#base-url]

```text
https://api.fieldgeist.com
```

All 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 [#endpoints]

### Verify [#verify]

| Method | Path | Does |
| --- | --- | --- |
| `POST` | [`/v1/verify/parse`](/api-reference/verify/parse) | Free text to USPS-standard components |
| `POST` | [`/v1/verify/lookup`](/api-reference/verify/lookup) | Parsed address to parcel |
| `GET` | [`/v1/verify/lookup/{fieldgeist_id}`](/api-reference/verify/lookup-by-id) | One parcel by its Fieldgeist ID |

Only answers with HTTP status `200` are billed. See [Credits and billing](/billing), and the [pricing page](https://fieldgeist.com/pricing) for rates.

## Requests [#requests]

- **Authentication:** `Authorization: Bearer <key>` on every request. See [Authentication](/authentication).
- **Bodies:** `POST` endpoints take a JSON body. Send `Content-Type: application/json`.
- **Responses:** JSON, including every error from these endpoints. Errors share one shape:

```json
{ "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](/api-reference/errors).

## Response headers [#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 [#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](https://fieldgeist.com/terms)).

Each product's paths start with its name (`/v1/verify/...`).
## Calling from a browser [#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 [#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 `null` in lookup responses and are left out of parse `components`.
- Coordinates are decimal degrees (`lat`, `lon`).