Methods and structures

Geoname description from https://download.geonames.org/export/dump/:

Note that in the cities1000 dataset, the name is a city name.

The main 'geoname' table has the following fields :

geonameid : integer id of record in geonames database name : name of geographical point (utf8) varchar(200) asciiname : name of geographical point in plain ascii characters, varchar(200) alternatenames : alternatenames, comma separated, ascii names automatically transliterated, convenience attribute from alternatename table, varchar(10000) latitude : latitude in decimal degrees (wgs84) longitude : longitude in decimal degrees (wgs84) feature class : see http://www.geonames.org/export/codes.html, char(1) feature code : see http://www.geonames.org/export/codes.html, varchar(10) country code : ISO-3166 2-letter country code, 2 characters cc2 : alternate country codes, comma separated, ISO-3166 2-letter country code, 200 characters admin1 code : fipscode (subject to change to iso code), see exceptions below, see file admin1Codes.txt for display names of this code; varchar(20) admin2 code : code for the second administrative division, a county in the US, see file admin2Codes.txt; varchar(80) admin3 code : code for third level administrative division, varchar(20) admin4 code : code for fourth level administrative division, varchar(20) population : bigint (8 byte int) elevation : in meters, integer dem : digital elevation model, srtm3 or gtopo30, average elevation of 3''x3'' (ca 90mx90m) or 30''x30'' (ca 900mx900m) area in meters, integer. srtm processed by cgiar/ciat. timezone : the iana timezone id (see file timeZone.txt) varchar(40) modification date : date of last modification in yyyy-MM-dd format

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

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

The second constructor is used to create the Geocoder from the geoname data that it automatically downloads on first run.

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_raw_geoname_data(;data_dir="./data", geo_file="cities1000")

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).

process_geoname_data(;data_dir="./data", geo_file="cities1000", header =collect(keys(COLUMN_TYPE)), select=DEFAULT_GEONAME_SELECT)

Process the raw geoname data and save it as a csv. Only selected columns are stored in the csv file. Removes the zip file.

read_data(;data_dir="./data", geo_file="cities1000", select=DEFAULT_DECODER_OUTPUT) => DataFrame

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