Skip to content

Latest commit

 

History

History
549 lines (438 loc) · 25.9 KB

README_API_GUIDE.md

File metadata and controls

549 lines (438 loc) · 25.9 KB
Raw

Guide to Geocoding APIs

This is a list of geocoding APIs supported by the Geocoder gem. Before using any API in a production environment, please read its official Terms of Service (links below).

Table of Contents

Street Address Lookups

Google (:google)

Google Maps API for Work (:google_premier)

Similar to :google, with the following differences:

  • API key: required, plus client and channel (set Geocoder.configure(lookup: :google_premier, api_key: [key, client, channel]))
  • Key signup: https://developers.google.com/maps/premium/
  • Quota: 100,000 requests/24 hrs, 10 requests/second

Google Places Details (:google_places_details)

The Google Places Details API is not, strictly speaking, a geocoding service. It accepts a Google place_id and returns address information, ratings and reviews. A place_id can be obtained from the Google Places Search lookup (:google_places_search) and should be passed to Geocoder as the first search argument: Geocoder.search("ChIJhRwB-yFawokR5Phil-QQ3zM", lookup: :google_places_details).

Google Places Search (:google_places_search)

The Google Places Search API is the geocoding service of Google Places API. It returns very limited location data, but it also returns a place_id which can be used with Google Place Details to get more detailed information. For a comparison between this and the regular Google Geocoding API, see https://maps-apis.googleblog.com/2016/11/address-geocoding-in-google-maps-apis.html

  • Same specifications as Google Places Details (see above).

Bing (:bing)

Nominatim (:nominatim)

PickPoint (:pickpoint)

LocationIQ (:location_iq)

OpenCageData (:opencagedata)

Yandex (:yandex)

Geocoder.ca (:geocoder_ca)

  • API key: none
  • Quota: ?
  • Region: US, Canada, Mexico
  • SSL support: no
  • Languages: English
  • Documentation: https://geocoder.ca/?premium_api=1
  • Terms of Service: http://geocoder.ca/?terms=1
  • Limitations: "Under no circumstances can our data be re-distributed or re-sold by anyone to other parties without our written permission."

Mapbox (:mapbox)

  • API key: required
  • Dataset: Uses mapbox.places dataset by default. Specify the mapbox.places-permanent dataset by setting: Geocoder.configure(mapbox: {dataset: "mapbox.places-permanent"})
  • Key signup: https://www.mapbox.com/pricing/
  • Quota: depends on plan
  • Region: complete coverage of US and Canada, partial coverage elsewhere (see for details: https://www.mapbox.com/developers/api/geocoding/#coverage)
  • SSL support: yes
  • Languages: English
  • Extra params (see Mapbox docs for more):
    • :country - restrict results to a specific country, e.g., us or ca
    • :types - restrict results to categories such as address, neighborhood, postcode
    • :proximity - bias results toward a lng,lat, e.g., params: { proximity: "-84.0,42.5" }
  • Documentation: https://www.mapbox.com/developers/api/geocoding/
  • Terms of Service: https://www.mapbox.com/tos/
  • Limitations: For mapbox.places dataset, must be displayed on a Mapbox map; Cache results for up to 30 days. For mapbox.places-permanent dataset, depends on plan.
  • Notes: Currently in public beta.

Mapquest (:mapquest)

Here/Nokia (:here)

  • API key: required (set Geocoder.configure(api_key: [app_id, app_code]))
  • Quota: Depending on the API key
  • Region: world
  • SSL support: yes
  • Languages: The preferred language of address elements in the result. Language code must be provided according to RFC 4647 standard.
  • Extra params:
    • :bounds - pass NW and SE coordinates as an array of two arrays to bias results towards a viewport
    • :country - pass the country or list of countries using the country code (3 bytes, ISO 3166-1-alpha-3) or the country name, to filter the results
  • Documentation: http://developer.here.com/rest-apis/documentation/geocoder
  • Terms of Service: http://developer.here.com/faqs#l&t
  • Limitations: ?

ESRI (:esri)

  • API key: optional (set Geocoder.configure(esri: {api_key: ["client_id", "client_secret"]}))
  • Quota: Required for some scenarios (see Terms of Service)
  • Region: world
  • SSL support: yes
  • Languages: English
  • Documentation: https://developers.arcgis.com/rest/geocode/api-reference/overview-world-geocoding-service.htm
  • Terms of Service: http://www.esri.com/legal/software-license
  • Limitations: Requires API key if results will be stored. Using API key will also remove rate limit.
  • Notes: You can specify which projection you want to use by setting, for example: Geocoder.configure(esri: {outSR: 102100}). If you will store results, set the flag and provide API key: Geocoder.configure(esri: {api_key: ["client_id", "client_secret"], for_storage: true}). If you want to, you can also supply an ESRI token directly: Geocoder.configure(esri: {token: Geocoder::EsriToken.new('TOKEN', Time.now + 1.day})

Pelias (:pelias)

Data Science Toolkit (:dstk)

Data Science Toolkit provides an API whose response format is like Google's but which can be set up as a privately hosted service.

Baidu (:baidu)

Tencent (:tencent)

Geocodio (:geocodio)

  • API key: required
  • Quota: 2,500 free requests/day then purchase $0.0005 for each, also has volume pricing and plans.
  • Region: US & Canada
  • SSL support: yes
  • Languages: en
  • Documentation: https://geocod.io/docs/
  • Terms of Service: https://geocod.io/terms-of-use/
  • Limitations: No restrictions on use

SmartyStreets (:smarty_streets)

Geoportail.lu (:geoportail_lu)

Postcodes.io (:postcodes_io)

  • API key: none
  • Quota: ?
  • Region: UK
  • SSL support: yes
  • Languages: English
  • Documentation: http://postcodes.io/docs
  • Terms of Service: ?
  • Limitations: UK postcodes only

PostcodeAnywhere UK (:postcode_anywhere_uk)

LatLon.io (:latlon)

  • API key: required
  • Quota: Depends on the user's plan (free and paid plans available)
  • Region: US
  • SSL support: yes
  • Languages: en
  • Documentation: https://latlon.io/documentation
  • Terms of Service: ?
  • Limitations: No restrictions on use

Base Adresse Nationale FR (:ban_data_gouv_fr)

AMap (:amap)

IP Address Lookups

IPInfo.io (:ipinfo_io)

FreeGeoIP (:freegeoip) - DISCONTINUED

Pointpin (:pointpin)

  • API key: required
  • Quota: 50,000/mo for €9 through 1m/mo for €49
  • Region: world
  • SSL support: yes
  • Languages: English
  • Documentation: https://pointp.in/docs/get-started
  • Terms of Service: https://pointp.in/terms
  • Limitations: ?
  • Notes: To use Pointpin set Geocoder.configure(ip_lookup: :pointpin, api_key: "your_pointpin_api_key").

Telize (:telize)

  • API key: required
  • Quota: 1,000/day for $7/mo through 100,000/day for $100/mo
  • Region: world
  • SSL support: yes
  • Languages: English
  • Documentation: https://market.mashape.com/fcambus/telize
  • Terms of Service: ?
  • Limitations: ?
  • Notes: To use Telize set Geocoder.configure(ip_lookup: :telize, api_key: "your_api_key"). Or configure your self-hosted telize with the host option: Geocoder.configure(ip_lookup: :telize, telize: {host: "localhost"}).

MaxMind Legacy Web Services (:maxmind)

  • API key: required
  • Quota: Request Packs can be purchased
  • Region: world
  • SSL support: yes
  • Languages: English
  • Documentation: http://dev.maxmind.com/geoip/legacy/web-services/
  • Terms of Service: ?
  • Limitations: ?
  • Notes: You must specify which MaxMind service you are using in your configuration. For example: Geocoder.configure(maxmind: {service: :omni}).

Baidu IP (:baidu_ip)

MaxMind GeoIP2 Precision Web Services (:maxmind_geoip2)

  • API key: required
  • Quota: Request Packs can be purchased
  • Region: world
  • SSL support: yes
  • Languages: English
  • Documentation: http://dev.maxmind.com/geoip/geoip2/web-services/
  • Terms of Service: ?
  • Limitations: ?
  • Notes: You must specify which MaxMind service you are using in your configuration, and also basic authentication. For example: Geocoder.configure(maxmind_geoip2: {service: :country, basic_auth: {user: '', password: ''}}).

Ipstack (:ipstack)

  • API key: required (see https://ipstack.com/product)
  • Quota: 10,000 requests per month (with free API Key, 50,000/day and up for paid plans)
  • Region: world
  • SSL support: yes ( only with paid plan )
  • Languages: English, German, Spanish, French, Japanese, Portugues (Brazil), Russian, Chinese
  • Documentation: https://ipstack.com/documentation
  • Terms of Service: ?
  • Limitations: ?
  • Notes: To use Ipstack set Geocoder.configure(ip_lookup: :ipstack, api_key: "your_ipstack_api_key"). Supports the optional params: :hostname, :security, :fields, :language (see API documentation for details).

IP-API.com (:ipapi_com)

DB-IP.com (:db_ip_com)

Ipdata.co (:ipdata_co)

IP2Location (:ip2location)

  • API key: optional (20 free demo queries per day)
  • Quota: up to 100k credits with paid API key
  • Region: world
  • SSL support: yes
  • Languages: English
  • Documentation: https://www.ip2location.com/web-service
  • Terms of Service: https://www.ip2location.com/web-service
  • Notes: With the non-free version, specify your desired package: Geocoder.configure(ip2location: {package: "WSX"}) (see API documentation for package details).

Local IP Address Lookups

MaxMind Local (:maxmind_local) - EXPERIMENTAL

This lookup provides methods for geocoding IP addresses without making a call to a remote API (improves speed and availability). It works, but support is new and should not be considered production-ready. Please report any bugs you encounter.

  • API key: none (requires the GeoLite City database which can be downloaded from MaxMind)
  • Quota: none
  • Region: world
  • SSL support: N/A
  • Languages: English
  • Documentation: http://www.maxmind.com/en/city
  • Terms of Service: ?
  • Limitations: ?
  • Notes: There are two supported formats for MaxMind local data: binary file, and CSV file imported into an SQL database. You must download a database from MaxMind and set either the :file or :package configuration option for local lookups to work.

To use a binary file you must add the geoip (or jgeoip for JRuby) gem to your Gemfile or have it installed in your system, and specify the path of the MaxMind database in your configuration. For example:

Geocoder.configure(ip_lookup: :maxmind_local, maxmind_local: {file: File.join('folder', 'GeoLiteCity.dat')})

To use a CSV file you must import it into an SQL database. The GeoLite City and Country packages are supported. Configure like so:

Geocoder.configure(ip_lookup: :maxmind_local, maxmind_local: {package: :city})

You can generate ActiveRecord migrations and download and import data via provided rake tasks:

# generate migration to create tables
rails generate geocoder:maxmind:geolite_city

# download, unpack, and import data
rake geocoder:maxmind:geolite:load PACKAGE=city

You can replace city with country in any of the above tasks, generators, and configurations.

GeoLite2 (:geoip2)

This lookup provides methods for geocoding IP addresses without making a call to a remote API (improves speed and availability). It works, but support is new and should not be considered production-ready. Please report any bugs you encounter.

  • API key: none (requires a GeoIP2 or free GeoLite2 City or Country binary database which can be downloaded from MaxMind)

  • Quota: none

  • Region: world

  • SSL support: N/A

  • Languages: English

  • Documentation: http://www.maxmind.com/en/city

  • Terms of Service: ?

  • Limitations: ?

  • Notes: You must download a binary database file from MaxMind and set the :file configuration option. The CSV format databases are not yet supported since they are still in alpha stage. Set the path to the database file in your configuration:

    Geocoder.configure( ip_lookup: :geoip2, geoip2: { file: File.join('folder', 'GeoLite2-City.mmdb') } )

You must add either the hive_geoip2 gem (native extension that relies on libmaxminddb) or the maxminddb gem (pure Ruby implementation) to your Gemfile or have it installed in your system. The pure Ruby gem (maxminddb) will be used by default. To use hive_geoip2:

Geocoder.configure(
  ip_lookup: :geoip2,
  geoip2: {
    lib: 'hive_geoip2',
    file: File.join('folder', 'GeoLite2-City.mmdb')
  }
)

Copyright (c) 2009-18 Alex Reisner, released under the MIT license.