Geocode Address Data
Automatically enrich location data using the Google Maps Geocoding API to convert addresses into geographic coordinates and vice-versa.
The Geocode plugin for Flatfile automatically enriches location data using the Google Maps Geocoding API. Its primary purpose is to convert addresses into geographic coordinates (latitude and longitude) and vice-versa.
Use cases include:
- Forward Geocoding: Automatically populating latitude and longitude fields from a given address field
- Reverse Geocoding: Automatically populating a formatted address from given latitude and longitude fields
- Data Enrichment: Extract and add supplementary location data to records, such as country and postal code
The plugin operates during the data commit phase (commit:created
), processing records in bulk before they are finalized.
Installation
Install the plugin using npm:
Configuration & Parameters
The plugin is configured by passing a configuration object to the enrichGeocode
function.
Parameter | Type | Default | Description |
---|---|---|---|
sheetSlug | string | "addresses" | The slug of the sheet you want the plugin to process |
addressField | string | "address" | The field key/name in your sheet that contains the address to be geocoded |
latitudeField | string | "latitude" | The field key/name in your sheet for the latitude value |
longitudeField | string | "longitude" | The field key/name in your sheet for the longitude value |
autoGeocode | boolean | true | A flag to enable or disable the automatic geocoding process |
Default Behavior
If no configuration is provided, the plugin will attempt to run on a sheet with the slug “addresses”, looking for an “address” field to geocode and populating “latitude” and “longitude” fields.
Usage Examples
Basic Usage
Custom Configuration
Advanced Usage - Direct API Function
API Reference
enrichGeocode(config)
The main entry point for the plugin. Returns a bulkRecordHook
compatible with the Flatfile listener’s use()
method.
Parameters:
config
(object): Configuration object with the parameters described above
Returns:
A function that can be passed to listener.use()
and will be executed on the commit:created
event.
performGeocoding(input, apiKey)
An async function that makes a direct call to the Google Maps Geocoding API for both forward and reverse geocoding.
Parameters:
input
(object): Must contain either:address
(string): The address to geocodelatitude
(number) andlongitude
(number): The coordinates to reverse geocode
apiKey
(string): Your Google Maps Geocoding API key
Returns: A Promise that resolves to either:
Success (GeocodingResult):
Failure (GeocodingError):
Example with Error Handling:
Notes
API Key Requirement
A valid Google Maps Geocoding API key is required for this plugin to function. The plugin will look for the key in the environment variables as GOOGLE_MAPS_API_KEY
or in Flatfile secrets with the name GOOGLE_MAPS_API_KEY
.
Data Enrichment and Sheet Configuration
Upon successful geocoding, the plugin will attempt to set values for the following fields on the record: latitude
, longitude
, formatted_address
, country
, and postal_code
. Your Flatfile Sheet must be configured with these fields to store the enriched data. The latitude and longitude fields are configurable; the others are hardcoded.
Error Handling Pattern
If the Google Maps API returns an error (e.g., ZERO_RESULTS
, REQUEST_DENIED
) or if the network request fails, the plugin will not halt the import process. Instead, it will add an error message to the specific record and field that caused the issue using record.addError()
. This allows users to see which records failed to geocode and why directly in the Flatfile UI.
Event Trigger
The plugin is designed to run on the listener.on('commit:created')
event. This means it processes data after a user has reviewed their data and clicked the final submit button, but before the data is sent to its final destination.