# API overview (/api-reference/overview)

## Base URL [#base-url]

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

All endpoints are served over HTTPS.

## Endpoints [#endpoints]

| Method | Path | Does |
| --- | --- | --- |
| `POST` | [`/v1/verify/parse`](/api-reference/parse) | Free text to USPS-standard components |
| `POST` | [`/v1/verify/lookup`](/api-reference/lookup) | Parsed address to parcel |
| `GET` | [`/v1/verify/lookup/{fieldgeist_id}`](/api-reference/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, 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 [#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)).

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 [#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`).