Methods and structures

Geocoder(cities_data::AbstractDataFrame; filters::Vector{Function} = Function[])
Geocoder(;data_dir::String=DATA_DIR, geo_file::String=GEO_FILE, filters::Vector{Function} = Function[])

Geocoder structure that holds the reference points and their labels (city name and country code).

decode(gc::Geocoder, point) => NamedTuple{(:country, :country_code, :city), Tuple{String, String, String}}

Decode for single point. If processing many points, preferably use decode(gc, points) instead of using this method in a loop.

decode(gc::Geocoder, points) => Array{NamedTuple{(:country, :country_code, :city), Tuple{String, String, String}}}

Return country name and city for collection of points. Points should be either an array of staticaly sized arrays (e.g. StaticArrays) or a Matrix (see NearestNeighbors.jl documentation for details).

The country and city is determined by the nearest neighbor search in the labelled list of city locations from geonames.org. As such, the results may not be exactly accurate (e.g searches for points close to borders or in the middle of nowhere).

Nearest neighbor search uses the euclidian metric in the space of lat/lon coordinates.

# Example
julia> gc = Geocoder();
julia> ReverseGeocode.decode(gc, [SA[49.5863897, 17.2627342], SA[63.3342550, 12.0280064]])
2-element Array{Tuple{String,String},1}:
 (country="Czechia", country_code="CZ", city="Olomouc")
 (country="Norway", country_code="NO", city="Meråker")

Download and resave the country codes csv from geonames. Country codes are part of the package so this function does not usually need to run during install.

download_data(;data_dir="./data", geo_file="cities1000", header=COLUMNS)

Download dump from geonames.org. This function fetches a file of cities with a population > 1000 (and seats of administrations of ceratain country subdivisions, other options are population 500, 5000, 15000, see geonames.org for details). The dump is unpacked and city name, coordinates and country code are saved in a .csv file for use in the Geocoder.

read_data(;data_dir="./data", geo_file="cities1000")

Load coordinates, country codes and city names from the .csv saved export of the geonames file. Make sure to call download_data() before read_data().