README_API_GUIDE.md
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).
:amazon_location_service):index_name - the name of the place index resource you want to use for the search:max_results - return at most this many results:bias_position - bias the results toward a given point, defined as [latitude, longitude]:filter_b_box - a bounding box that you specify to filter your results to coordinates within the box's boundaries, defined as [longitude_sw, latitude_sw, longitude_ne, latitude_ne]:filter_countries - an array of countries you want to geocode within, named by ISO 3166 country codes, e.g. ['DEU', 'FRA']aws-sdk or aws-sdk-locationservice gem, version 1.4.0 or greater. Geocoder.configure(
lookup: :amazon_location_service,
amazon_location_service: {
index_name: 'YOUR_INDEX_NAME_GOES_HERE',
}
)
api_key parameter in the geocoder configuration:
Geocoder.configure(
lookup: :amazon_location_service,
amazon_location_service: {
index_name: 'YOUR_INDEX_NAME_GOES_HERE',
api_key: {
region: 'YOUR_INDEX_REGION',
access_key_id: 'YOUR_AWS_ACCESS_KEY_ID_GOES_HERE',
secret_access_key: 'YOUR_AWS_SECRET_ACCESS_KEY_GOES_HERE',
}
}
)
:azure)Geocoder.configure(lookup: :azure, api_key: "your_api_key", azure: { limit: your_limit }) (default 10).:bing)Geocoder.configure(lookup: :bing, api_key: key)):esri)Geocoder.configure(esri: {api_key: ["client_id", "client_secret"]}))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}):geoapify)Geocoder.configure(lookup: :geoapify, api_key: "your_api_key")):limit - restrict the maximum amount of returned results, e.g. limit: 5:autocomplete - Use the automplete API, only when doing forward geocoding e.g. autocomplete: true:type - restricts the type of the results, see API documentation for
available types, e.g. params: { type: 'amenity' }:filter - filters results by country, boundary or circle, e.g.
params: { filter: 'countrycode:de,es,fr' }, see API documentation
for available filters:bias - a location bias based on which results are prioritized, e.g.
params: { bias: 'countrycode:de,es,fr' }, see API documentation for
available biasesGeocoder.configure(lookup: :geoapify, api_key: "your_api_key").:google):bounds - pass SW and NE coordinates as an array of two arrays to bias results towards a viewport:google_place_id - pass true if search query is a Google Place ID:google_premier)Similar to :google, with the following differences:
Geocoder.configure(lookup: :google_premier, api_key: [key, client, channel])):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).
:fields - Requested API response fields (affects pricing, see the Google Places Details developer guide for available fields)Geocoder.configure(
google_places_details: {
fields: %w[business_status formatted_address geometry name photos place_id plus_code types]
}
)
: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
:fields - requested API response fields (affects pricing, see the source for available fields):locationbias - bias towards results in or near a specified area, using a string in one of the formats specified in the API documentation, e.g., locationbias: "point:-36.8509,174.7645"Geocoder.configure(
google_places_search: {
fields: %w[address_components adr_address business_status formatted_address geometry name
photos place_id plus_code types url utc_offset vicinity],
locationbias: "point:-36.8509,174.7645"
}
)
:here):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:location_iq):mapbox)mapbox.places dataset by default. Specify the mapbox.places-permanent dataset by setting: Geocoder.configure(mapbox: {dataset: "mapbox.places-permanent"}):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" }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.:mapquest)Geocoder.configure(http_headers: { "Referer" => "http://foo.com" })Geocoder.configure(mapquest: {open: true}) (defaults to licensed version):melissa_street):nominatim)Geocoder.configure(http_headers: { "User-Agent" => "your contact info" })). Data licensed under Open Database License (ODbL) (you must provide attribution).:opencagedata):osmnames)Open source geocoding engine which can be self-hosted. MapTiler.com hosts an installation for use with API key.
:host option in Geocoder.configure.:pelias)Open source geocoding engine which can be self-hosted. There are multiple service providers that can host Pelias instances (see notes).
endpoint option: Geocoder.configure(lookup: :pelias, api_key: 'your_api_key', pelias: {endpoint: 'self.hosted/pelias'}). Defaults to localhost.
:photon)Open source geocoding engine which can be self-hosted. Komoot hosts a public installation for fair use without the need for an API key (usage might be subject of change).
:limit - restrict the maximum amount of returned results, e.g. limit: 5:filter - extra filters for the search
:bbox (forward) - restricts the bounding box for the forward search,
e.g. filter: { bbox: [9.5, 51.5, 11.5, 53.5] }
(minLon, minLat, maxLon, maxLat).:osm_tag (forward) - filters forward search results by
tags and values,
e.g. filter: { osm_tag: 'tourism:museum' },
see API documentation for more information.:string (reverse) - filters the reverse search results by a query
string filter, e.g. filter: { string: 'query string filter' },:bias (forward) - a location bias based on which results are
prioritized, provide an option hash with the keys :latitude,
:longitude, and :scale (optional, default scale: 1.6), e.g.
bias: { latitude: 12, longitude: 12, scale: 4 }:radius (reverse) - a kilometer radius for the reverse geocoding search,
must be a positive number between 0-5000 (default radius: 1),
e.g. radius: 10:distance_sort (reverse) - defines if results are sorted by distance for
reverse search queries or not, only available if the distance sorting is
enabled for the instace, e.g. distance_sort: trueGeocoder.configure(lookup: :photon, photon: {host: "photon.example.org"}).:pickpoint):pc_miler)PC Miler (aka Trimble) provides geocoding services especially tailored to the trucking / logistics industry.
NA ('North America').:yandex):amap)Geocoder.configure(lookup: :amap, api_key: "your_api_key").:baidu)Geocoder.configure(lookup: :baidu, api_key: "your_api_key").:ban_data_gouv_fr):geocoder_ca):geocodio):geoportail_lu):latlon):nationaal_georegister_nl):pdok_nl):uk_ordnance_survey_names):postcode_anywhere_uk)Geocoder.configure(lookup: :postcode_anywhere_uk, api_key: 'your_api_key').:smarty_streets)Geocoder.configure(api_key: [id, token])):tencent)Geocoder.configure(lookup: :tencent, api_key: "your_api_key").:abstract_api):baidu_ip)Geocoder.configure(lookup: :baidu_ip, api_key: "your_api_key").:db_ip_com):freegeoip)Geocoder.configure(freegeoip: {host: 'api.ipstack.com'}). The service can also be self-hosted.:ipbase):ipapi_com):ip2location)Geocoder.configure(ip2location: {package: "WSX"}) (see API documentation for package details).:ipdata_co):ipgeolocation)Geocoder.configure(ip_lookup: :ipgeolocation, api_key: "your_ipgeolocation_api_key", use_https:true). Supports the optional params: { excludes: "continent_code"}, {fields: "geo"}, {lang: "ru"}, {output: "xml"}, {include: "hostname"}, {ip: "174.7.116.0"}) (see API documentation for details).:ipinfo_io):ipinfo_io_lite)A free-tier API access plan, which includes unlimited country-level geolocation information and unlimited basic ASN information. Geolocation information provided by the Lite API service includes country and continent information, while ASN information includes ASN, organization name, and domain name.
:ipqualityscore):ipregistry):ipstack)Geocoder.configure(ip_lookup: :ipstack, api_key: "your_ipstack_api_key"). Supports the optional params: :hostname, :security, :fields, :language (see API documentation for details).:maxmind)Geocoder.configure(maxmind: {service: :omni}).:maxmind_geoip2)Geocoder.configure(maxmind_geoip2: {service: :country, basic_auth: {user: '', password: ''}}).:pointpin)Geocoder.configure(ip_lookup: :pointpin, api_key: "your_pointpin_api_key").:telize)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"}).:twogis):ip2location_io):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: Caching is not supported.
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')
}
)
:maxmind_local) - EXPERIMENTALThis 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.
: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 LICENSE_KEY=<KEY>
You can replace city with country in any of the above tasks, generators, and configurations.
:ip2location_lite)This lookup provides methods for geocoding IP addresses without making a call to a remote API (improves speed and availability).
API key: none (requires a IP2Location or FREE IP2Location LITE binary database which can be downloaded from IP2Location LITE)
Quota: none
Region: world
SSL support: N/A
Languages: English
Documentation: https://lite.ip2location.com/
Terms of Service: https://lite.ip2location.com/
Notes: You must download a binary database (BIN) file from IP2Location LITE and set the :file configuration option. Set the path to the database file in your configuration:
Geocoder.configure( ip_lookup: :ip2location_lite, ip2location_lite: { file: File.join('folder', 'IP2LOCATION-LITE-DB11.BIN') } )
You must add the ip2location_ruby gem (pure Ruby implementation) to your Gemfile or have it installed in your system.
Copyright (c) 2009-2021 Alex Reisner, released under the MIT license.