Geocoding Services • tidygeocoder

Overview

The supported geocoding services are shown in the table below. The method is used to select the geocoding service in tidygeocoder functions such as geo() and reverse_geo(). The usage rate limitations are listed for the free tier of the service when applicable and many services have faster rates available with paid plans.

Also note that there are many other considerations when selecting a geocoding service such as if the service uses open source data with permissive licensing, how the service uses or stores your data, and if there are restrictions on how you can use the data provided by the service. Refer to each service’s documentation for details.

Service	Method	API Key Required	Batch Geocoding	Usage Limitations	API Documentation
Nominatim	`osm`			1 query per second	docs
US Census	`census`		✅		docs
ArcGIS	`arcgis`				docs
Geocodio	`geocodio`	✅	✅	1000 queries per minute (free tier)	docs
Location IQ	`iq`	✅		60 queries per minute (free tier)	docs
Google	`google`	✅		50 queries per second	docs
OpenCage	`opencage`	✅		1 query per second (free tier)	docs
Mapbox	`mapbox`	✅		600 queries per minute (free tier)	docs
HERE	`here`	✅	✅	5 queries per second (free tier)	docs
TomTom	`tomtom`	✅	✅	5 queries per second (free tier)	docs
MapQuest	`mapquest`	✅	✅		docs
Bing	`bing`	✅	✅		docs
Geoapify	`geoapify`	✅		5 queries per second (free tier)	docs

Highlights:

The US Census service does not support reverse geocoding and is limited to the United States.
Geocodio is limited to the United States and Canada.
The US Census and Nominatim (“osm”) services are free and do not require an API key.
ArcGIS can be used for free without an API key, but some features require a paid subscription and an API key.
Geoapify, Geocodio, Location IQ, OpenCage, Mapbox, HERE, TomTom, MapQuest, and Bing are commercial services that offer free tiers.
The Google service has no free tier and bills per query.

Data Privacy

Due diligence must be exercised when geocoding sensitive data as tidygeocoder utilizes third party web services to perform geocoding. Within the context of healthcare, using patient or study subject address data with a third party geocoding service can risk violating privacy rules for International Review Boards (IRBs) and HIPAA.

Further details on possible risk are described here. Refer to the documentation on your selected geocoding service (see links above) for information on how your data will be utilized and stored.

Some options you could consider if the privacy of your data is a concern:

The Geocodio service offers a HIPAA compliant API. To enable the use of this API in tidygeocoder, you can use the api_options=list(geocodio_hipaa=TRUE) parameter.
The Nominatim service (method="osm") can be installed and hosted locally so that data does not leave your local network. See the Nominatim website for installation instructions. You can use a locally hosted Nominatim service with tidygeocoder by specifying its address with the api_url parameter.

See the geo() or reverse_geo() documentation pages for more documentation on the parameters mentioned above.

Usage Notes

When used in batch mode, the US Census geocoder will return NA data when there are multiple results available for an address. The expectation is that you would see that a “Tie” is indicated and use single address geocoding to return the results for these addresses. See #87 for details.
When performing reverse geocoding, the Mapbox service requires a types parameter to be set if limit > 1. See #104.
The Bing batch geocoder does not use the limit parameter (#106).
The US Census service supports street-level addresses only (ie. “11 Wall St New York, NY” is OK but “New York, NY” is not).
The Mapbox service is capable of performing batch geocoding when using the permanent endpoint, but this capability is not currently implemented in tidygeocoder. If you’d like to add this capability to the package see #73.
The ArcGIS service is capable of performing batch geocoding, but this capability is not currently implemented in tidygeocoder. If you’d like to add this capability see #102.
For the ArcGIS service, an API Key is not strictly required if the service is used for search capabilities only (see Free vs. paid operations). It is possible to include an API Key on the request via the custom_query parameter:

tidygeocoder::geo(address = "New York, USA", method = "arcgis",
  custom_query = list(token = "<API_KEY>"))

API Parameters

The api_parameter_reference maps the API parameters for each geocoding service to a common set of “generic” parameters. The generic_name below is the generic parameter name while the api_name is the parameter name for the specified geocoding service (method). Refer to ?api_parameter_reference for more details.

API Key Retrieval

API keys are retrieved from environmental variables. The name of the environmental variable used for each service is stored in the api_key_reference dataset. See ?api_key_reference.

method	env_var
geocodio	GEOCODIO_API_KEY
iq	LOCATIONIQ_API_KEY
google	GOOGLEGEOCODE_API_KEY
opencage	OPENCAGE_KEY
mapbox	MAPBOX_API_KEY
here	HERE_API_KEY
tomtom	TOMTOM_API_KEY
mapquest	MAPQUEST_API_KEY
bing	BINGMAPS_API_KEY
geoapify	GEOAPIFY_KEY

Minimum Time Per Query

The minimum time (in seconds) required per query to comply with the usage limitations policies of each geocoding service is stored in the min_time_reference dataset. See ?min_time_reference.

method	min_time	description
osm	1.00	1 query per second
geocodio	0.06	1000 queries per minute (free tier)
iq	1.00	60 queries per minute (free tier)
google	0.02	50 queries per second
opencage	1.00	1 query per second (free tier)
mapbox	0.10	600 queries per minute (free tier)
tomtom	0.20	5 queries per second (free tier)
here	0.20	5 queries per second (free tier)
geoapify	0.20	5 queries per second (free tier)

Links to the usage policies for each geocoding service:

Batch Query Size Limits

The maximum number of inputs (geographic coordinates or addresses) per batch query for each geocoding service is stored in the batch_limit_reference dataset. See ?batch_limit_reference.

method	batch_limit
census	10,000
geocodio	10,000
tomtom	10,000
here	1,000,000
mapquest	100
bing	50