Auto-geocode new Airtable addresses with OpenStreetMap

Build a code workflow that geocodes addresses landing in an Airtable table and writes the results back onto the same row.

Trigger: poll Airtable for new records (event type new_record) on a single configured base and table. At setup, ask me which base and table to watch, and which field on that table holds the street address.

For each new record, run these steps in order:

1. Read the address field from the triggering record. If it is empty, skip the record entirely (do not update it).

2. Call OpenStreetMap Nominatim Search (Forward Geocode) with q = the address, format = jsonv2, addressdetails = 1, limit = 1. Send a descriptive User-Agent header identifying this workflow and include an email query parameter so OSM operators can reach us. Sleep at least 1100ms before any subsequent Nominatim call in the same run to stay under their 1 request per second fair-use cap.

3. Handle the response:

- If the response is an empty array, call Airtable Update Record on the triggering record with geocode_status = no_match and leave the coordinate fields blank. This prevents the row from being re-attempted on every poll.

- If Nominatim returns HTTP 429, wait 2 seconds and retry the same request once. If it still fails, update the record with geocode_status = rate_limited so a human can re-run it later.

- If the response has at least one hit, take the first result and map it as follows: lat -> latitude (number), lon -> longitude (number), address.country -> country, address.state -> state (fall back to address.region or address.province if state is missing), address.postcode -> postcode, display_name -> display_name, and set geocode_status = ok.

4. Call Airtable Update Record (PATCH) on the triggering record with only the mapped fields. Do not touch the original address field or any column the workflow did not produce.

Configuration to expose to the user at setup: the Airtable base id, the table id or name, the address field name, and the destination field names for latitude, longitude, country, state, postcode, display_name, and geocode_status. Default the destination names to those exact strings but let me override them in case my columns are named differently.

Important constraints: this is a deterministic code workflow with no LLM step. The Nominatim service is no-auth. Airtable uses OAuth and needs data.records:read and data.records:write scopes plus schema.bases:read so the workflow can resolve field ids. Respect Airtable's 5 requests per second per base limit by processing one record per trigger fire; do not batch.