Quickstart
Create an API key, parse an address and match it to a parcel.
This page takes you from a new account to a parsed address and a parcel match. You need an email address and a terminal.
Create an account
Go to app.fieldgeist.com/sign-up and enter your email. We email you a 6-digit code; enter it to sign in. There are no passwords.
The first time you sign in, the portal asks for your name and a team name. A team owns its API keys, usage and billing. Every new account starts with free credits.
Create an API key
In the portal, open API keys and select Create key. Name it after where it will run, such as "Production server".
Copy the key when it appears. It starts with fg_live_ and is shown only once. Store it in your secrets manager, then put it in an environment variable for this walkthrough:
export FIELDGEIST_API_KEY="fg_live_..."Parse an address
curl https://api.fieldgeist.com/v1/verify/parse \
-H "Authorization: Bearer $FIELDGEIST_API_KEY" \
-H "Content-Type: application/json" \
-d '{"line": "400 Broad St, Seattle, WA 98109"}'The response splits the line into USPS Publication 28 components and renders the standardized delivery lines:
{
"input": "400 Broad St, Seattle, WA 98109",
"type": "street",
"components": {
"city": "SEATTLE",
"addressNumber": "400",
"streetSuffix": "ST",
"streetName": "BROAD",
"state": "WA",
"zip5": "98109"
},
"lines": ["400 BROAD ST", "SEATTLE WA 98109"],
"warnings": [],
"confidence": 0.9999376787822885,
"model": { "name": "us-lex-1", "version": "0.1.0", "backend": "model" }
}An empty warnings array and a confidence close to 1 mean the parse is clean. See Confidence and warnings for what to do when they aren't.
Match it to a parcel
Send the parse response, unchanged, to the lookup endpoint:
curl https://api.fieldgeist.com/v1/verify/parse \
-H "Authorization: Bearer $FIELDGEIST_API_KEY" \
-H "Content-Type: application/json" \
-d '{"line": "400 Broad St, Seattle, WA 98109"}' \
| curl https://api.fieldgeist.com/v1/verify/lookup \
-H "Authorization: Bearer $FIELDGEIST_API_KEY" \
-H "Content-Type: application/json" \
-d @-A matched answer carries one parcel:
{
"status": "matched",
"fieldgeist_id": "adr_01JA2Z3Y4X5W6V7T8S9R0QPNMA",
"building_id": null,
"apn": "198520-0495",
"fips": "53033",
"lat": 47.620494,
"lon": -122.349235,
"matchConfidence": 1,
"candidates": [],
"searched": ["matchkey/v3.2/zip5=98109/part.parquet"],
"readPath": "chunk",
"fuzzy": false
}Parcel values in these docs are illustrative. Run the request to see the real parcel.
Store the fieldgeist_id. It's how you refer to this parcel later, and you can fetch it again with Look up by Fieldgeist ID at a lower price than a new lookup.
Next steps
- Handle every lookup status:
ambiguous,unit_requiredandnot_foundincluded. - Errors: every error code the API returns.
- Credits and billing: when a request is billed and how to control spend.
- Try addresses without writing code in the portal's Verify page. Its requests are billed like API requests.