Geocoding does not rely on any external API. It relies on an internal (huge) database of 165,602 coordinates corresponding to cities of more than 500 inhabitants (see Data sources for more details).

Compile, test and try

Compilation:

rebar compile

Tests:

rebar eunit

Usage:

> erl -pa _build/default/lib/geocoding/ebin/ 
Erlang/OTP 23 [erts-11.1.8] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [hipe] [dtrace]

Eshell V11.1.8  (abort with ^G)
1> application:start(geocoding).
ok

2> geocoding:reverse(48.857929, 2.346707).
{ok,{2988507,europe,fr,<<"Paris">>,525.451956}}

3> geocoding:distance({48.857929, 2.346707}, {40.7630463, -73.973527}).
5832947

4> geocoding:lookup('FR', <<"paris">>).
{ok,{2988507,{48.85341,2.3488},europe,'FR',<<"Paris">>}}

geocoding:reverse/2 returns the geoname id, continent name, country code (ISO 3166-1 alpha-2), city name, distance between city center and provided coordinates.

Installation

Erlang (rebar3):

{deps, [
  {geocoding, "0.4.0"}}
]}

Elixir (mix):

defp deps do
  [
    {:geocoding, "~> 0.4.0"}
  ]
end

Database rebuilding

An escript allows to rebuild your cities.txt data from geonames. It will fetch the last version of cities500.zip, unzip it, filter out city with too low population, and build continent name. It will generate a cities.txt.new file. Existing citiers.txt will not be erased.

> ./scripts/cities_builder.escript

If you want to replace your cities.txt, add --replace parameter. Old cities.txt will be renamed to cities.txt.old.

> ./scripts/cities_builder.escript --replace

Technical information

Algorithm

Reverse geocoding is done thanks to a k-d tree algorithm. We use Martin F. Krafft implementation. Original source code is here: https://github.com/kbranigan/libkdtree/tree/master/kdtree%2B%2B . It is embeded in an erlang driver.

From latitude/longitude coordinates, geocoding finds the nearest point in our locations database. Associated data are returned, as well as a distance between provided coordinates and real coordinates. Since reverse geocoding relies only on coordinates, strange behaviour may occured when a big city is near a small one: a point inside the big city and near its border may be associated to the small city because the small city coordinates will be nearest than the big city coordinates.

Data sources

All locations data come from https://www.geonames.org database (http://download.geonames.org/export/dump/cities500.zip - 2024-12-05):

• Locations without population have been excluded.
• PPLX (section of populated places) and PPLA5 (seat of a fifth-order administrative division) have been excluded.
• Fields have been reduced to: geonameId, latitude, longitude, country code (ISO-3166), standard name. A 6th fields have been added between longitude and country code: continent. Each field is separated by a tabulation.

Example:

2988507 48.85341        2.3488  europe  FR      Paris

Each location is associated to one of the following continents:

• africa (africa and islands nearby like Madagascar, Canary, La Réunion...)
• antarctica (only one country)
• asia (including russian cities after Ural Mountains)
• europe (including russian cities before Ural Mountains)
• oceania (including Australia continent and pacific islands)
• north america
• south america

Missing locations may be added on request.