Geonames (GeoNames-Elixir v1.0.5)
Geonames-Elixir is a simple wrapper around the API provided by geonames.org. All interaction with the API is provied by this module via easy to use functions.
Each API endpoint maps to a single function, all of which requiring a map containing the parameters of the request. If no arguments are required, then the hash can be omited as it will default to %{}
Examples
Below you will find a few examples on how to query the geonames API.
General search
Geonames.search %{ q: "London" }
Geonames.search %{ q: "London, United Kingdom" }
Find cities in a bounding box
Geonames.cities %{ north: 44.1, south: -9.9, east: -22.4, west: 55.2 }
Find earthquakes in a bounding box
Geonames.earthquakes %{ north: 44.1, south: -9.9, east: -22.4, west: 55.2, date: "2015-05-30" }
As you can see, the interface is very simple to use. All functions will return a map in the exact format returned by the API. Currently, Geonames-Elixir will make no attempt to format this response in any way.
Link to this section Summary
Functions
Makes a request to the GeoNames endpoint /astergdemJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /childrenJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /citiesJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /containsJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /countryCodeJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /countryInfoJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /countrySubdivisionJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /earthquakesJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /findNearbyJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /findNearbyPlaceNameJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /findNearbyPOIsOSMJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /findNearbyPostalCodesJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /findNearbyStreetsJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /findNearbyStreetsOSMJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /findNearByWeatherJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /findNearbyWikipediaJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /findNearestAddressJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /findNearestIntersectionJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /findNearestIntersectionOSMJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /getJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /gtopo30JSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /hierarchyJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /neighbourhoodJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /neighboursJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /oceanJSON
The arguments map may contain the following keys
Performs a simple get request to the specified URL. This is not specific to GeoNames and could be used for any basic GET request, but it assumes the response is in JSON.
Makes a request to the GeoNames endpoint /postalCodeCountryInfoJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /postalCodeLookupJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /postalCodeSearchJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /searchJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /siblingsJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /srtm1JSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /srtm3JSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /timezoneJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /weatherJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /weatherIcaoJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /wikipediaBoundingBoxJSON
The arguments map may contain the following keys
Makes a request to the GeoNames endpoint /wikipediaSearchJSON
The arguments map may contain the following keys
Link to this section Functions
astergdem(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /astergdemJSON
The arguments map may contain the following keys:
- lat
- lng
Each request parameter should be supplied in a map. For example,
Geonames.astergdem(%{
lat: "val",
lng: "val"
})
children(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /childrenJSON
The arguments map may contain the following keys:
- geonameId
- maxRows
- hierarchy
Each request parameter should be supplied in a map. For example,
Geonames.children(%{
geonameId: "val",
maxRows: "val",
hierarchy: "val"
})
cities(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /citiesJSON
The arguments map may contain the following keys:
- north
- south
- east
- west
- maxRows
Each request parameter should be supplied in a map. For example,
Geonames.cities(%{
north: "val",
south: "val",
east: "val",
west: "val",
maxRows: "val"
})
contains(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /containsJSON
The arguments map may contain the following keys:
- geonameId
- featureClass
- featureCode
Each request parameter should be supplied in a map. For example,
Geonames.contains(%{
geonameId: "val",
featureClass: "val",
featureCode: "val"
})
country_code(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /countryCodeJSON
The arguments map may contain the following keys:
- lat
- lng
- type
- radius
Each request parameter should be supplied in a map. For example,
Geonames.country_code(%{
lat: "val",
lng: "val",
type: "val",
radius: "val"
})
country_info(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /countryInfoJSON
The arguments map may contain the following keys:
- country
Each request parameter should be supplied in a map. For example,
Geonames.country_info(%{
country: "val"
})
country_subdivision(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /countrySubdivisionJSON
The arguments map may contain the following keys:
- lat
- lng
- radius
- level
Each request parameter should be supplied in a map. For example,
Geonames.country_subdivision(%{
lat: "val",
lng: "val",
radius: "val",
level: "val"
})
earthquakes(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /earthquakesJSON
The arguments map may contain the following keys:
- date
- east
- maxRows
- minMagnitude
- north
- south
- west
Each request parameter should be supplied in a map. For example,
Geonames.earthquakes(%{
date: "val",
east: "val",
maxRows: "val",
minMagnitude: "val",
north: "val",
south: "val",
west: "val"
})
find_nearby(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /findNearbyJSON
The arguments map may contain the following keys:
- featureClass
- featureCode
- lat
- lng
- localCountry
- maxRows
- radius
- style
Each request parameter should be supplied in a map. For example,
Geonames.find_nearby(%{
featureClass: "val",
featureCode: "val",
lat: "val",
lng: "val",
localCountry: "val",
maxRows: "val",
radius: "val",
style: "val"
})
find_nearby_place_name(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /findNearbyPlaceNameJSON
The arguments map may contain the following keys:
- cities
- lat
- lng
- localCountry
- maxRows
- radius
- style
Each request parameter should be supplied in a map. For example,
Geonames.find_nearby_place_name(%{
cities: "val",
lat: "val",
lng: "val",
localCountry: "val",
maxRows: "val",
radius: "val",
style: "val"
})
find_nearby_pois_osm(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /findNearbyPOIsOSMJSON
The arguments map may contain the following keys:
- lat
- lng
- maxRows
- radius
Each request parameter should be supplied in a map. For example,
Geonames.find_nearby_pois_osm(%{
lat: "val",
lng: "val",
maxRows: "val",
radius: "val"
})
find_nearby_postal_codes(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /findNearbyPostalCodesJSON
The arguments map may contain the following keys:
- cities
- country
- lat
- lng
- localCountry
- maxRows
- postalCode
- radius
- style
Each request parameter should be supplied in a map. For example,
Geonames.find_nearby_postal_codes(%{
cities: "val",
country: "val",
lat: "val",
lng: "val",
localCountry: "val",
maxRows: "val",
postalCode: "val",
radius: "val",
style: "val"
})
find_nearby_streets(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /findNearbyStreetsJSON
The arguments map may contain the following keys:
- lat
- lng
- maxRows
Each request parameter should be supplied in a map. For example,
Geonames.find_nearby_streets(%{
lat: "val",
lng: "val",
maxRows: "val"
})
find_nearby_streets_osm(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /findNearbyStreetsOSMJSON
The arguments map may contain the following keys:
- lat
- lng
- maxRows
- radius
Each request parameter should be supplied in a map. For example,
Geonames.find_nearby_streets_osm(%{
lat: "val",
lng: "val",
maxRows: "val",
radius: "val"
})
find_nearby_weather(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /findNearByWeatherJSON
The arguments map may contain the following keys:
- lat
- lng
- radius
Each request parameter should be supplied in a map. For example,
Geonames.find_nearby_weather(%{
lat: "val",
lng: "val",
radius: "val"
})
find_nearby_wikipedia(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /findNearbyWikipediaJSON
The arguments map may contain the following keys:
- country
- lat
- lng
- maxRows
- postalcode
- radius
Each request parameter should be supplied in a map. For example,
Geonames.find_nearby_wikipedia(%{
country: "val",
lat: "val",
lng: "val",
maxRows: "val",
postalcode: "val",
radius: "val"
})
find_nearest_address(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /findNearestAddressJSON
The arguments map may contain the following keys:
- lat
- lng
Each request parameter should be supplied in a map. For example,
Geonames.find_nearest_address(%{
lat: "val",
lng: "val"
})
find_nearest_intersection(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /findNearestIntersectionJSON
The arguments map may contain the following keys:
- lat
- lng
Each request parameter should be supplied in a map. For example,
Geonames.find_nearest_intersection(%{
lat: "val",
lng: "val"
})
find_nearest_intersection_osm(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /findNearestIntersectionOSMJSON
The arguments map may contain the following keys:
- lat
- lng
- maxRows
- radius
Each request parameter should be supplied in a map. For example,
Geonames.find_nearest_intersection_osm(%{
lat: "val",
lng: "val",
maxRows: "val",
radius: "val"
})
get(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /getJSON
The arguments map may contain the following keys:
- geonameId
Each request parameter should be supplied in a map. For example,
Geonames.get(%{
geonameId: "val"
})
gtopo30(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /gtopo30JSON
The arguments map may contain the following keys:
- lat
- lng
Each request parameter should be supplied in a map. For example,
Geonames.gtopo30(%{
lat: "val",
lng: "val"
})
hierarchy(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /hierarchyJSON
The arguments map may contain the following keys:
- geonameId
Each request parameter should be supplied in a map. For example,
Geonames.hierarchy(%{
geonameId: "val"
})
neighbourhood(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /neighbourhoodJSON
The arguments map may contain the following keys:
- lat
- lng
Each request parameter should be supplied in a map. For example,
Geonames.neighbourhood(%{
lat: "val",
lng: "val"
})
neighbours(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /neighboursJSON
The arguments map may contain the following keys:
- geonameId
- country
Each request parameter should be supplied in a map. For example,
Geonames.neighbours(%{
geonameId: "val",
country: "val"
})
ocean(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /oceanJSON
The arguments map may contain the following keys:
- lat
- lng
Each request parameter should be supplied in a map. For example,
Geonames.ocean(%{
lat: "val",
lng: "val"
})
perform_geonames_request(url)
Specs
Performs a simple get request to the specified URL. This is not specific to GeoNames and could be used for any basic GET request, but it assumes the response is in JSON.
This function will return one of two values
{ :ok, %{ ... }}
{ :error, "Reason" }
A successful request will return a parsed Map of the response. If an error occurs, an :error tuple will be returned with a string describing the error.
postal_code_country_info(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /postalCodeCountryInfoJSON
The arguments map may contain the following keys:
Each request parameter should be supplied in a map. For example,
Geonames.postal_code_country_info(%{
})
postal_code_lookup(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /postalCodeLookupJSON
The arguments map may contain the following keys:
- postalcode
- country
- maxRows
Each request parameter should be supplied in a map. For example,
Geonames.postal_code_lookup(%{
postalcode: "val",
country: "val",
maxRows: "val"
})
postal_code_search(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /postalCodeSearchJSON
The arguments map may contain the following keys:
- country
- countryBias
- east
- isReduced
- maxRows
- north
- operator
- placename
- placename_startsWith
- postalcode
- postalcode_startsWith
- south
- style
- west
Each request parameter should be supplied in a map. For example,
Geonames.postal_code_search(%{
country: "val",
countryBias: "val",
east: "val",
isReduced: "val",
maxRows: "val",
north: "val",
operator: "val",
placename: "val",
placename_startsWith: "val",
postalcode: "val",
postalcode_startsWith: "val",
south: "val",
style: "val",
west: "val"
})
search(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /searchJSON
The arguments map may contain the following keys:
- adminCode1
- adminCode2
- adminCode3
- cities
- continentCode
- country
- countryBias
- east
- featureClass
- featureCode
- fuzzy
- inclBbox
- isNameRequired
- maxRows
- name
- name_equals
- name_startsWith
- north
- operator
- orderby
- q
- searchlang
- south
- startRow
- style
- tag
- west
Each request parameter should be supplied in a map. For example,
Geonames.search(%{
adminCode1: "val",
adminCode2: "val",
adminCode3: "val",
cities: "val",
continentCode: "val",
country: "val",
countryBias: "val",
east: "val",
featureClass: "val",
featureCode: "val",
fuzzy: "val",
inclBbox: "val",
isNameRequired: "val",
maxRows: "val",
name: "val",
name_equals: "val",
name_startsWith: "val",
north: "val",
operator: "val",
orderby: "val",
q: "val",
searchlang: "val",
south: "val",
startRow: "val",
style: "val",
tag: "val",
west: "val"
})
siblings(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /siblingsJSON
The arguments map may contain the following keys:
- geonameId
Each request parameter should be supplied in a map. For example,
Geonames.siblings(%{
geonameId: "val"
})
srtm1(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /srtm1JSON
The arguments map may contain the following keys:
- lat
- lng
Each request parameter should be supplied in a map. For example,
Geonames.srtm1(%{
lat: "val",
lng: "val"
})
srtm3(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /srtm3JSON
The arguments map may contain the following keys:
- lat
- lng
Each request parameter should be supplied in a map. For example,
Geonames.srtm3(%{
lat: "val",
lng: "val"
})
timezone(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /timezoneJSON
The arguments map may contain the following keys:
- date
- lat
- lng
- radius
Each request parameter should be supplied in a map. For example,
Geonames.timezone(%{
date: "val",
lat: "val",
lng: "val",
radius: "val"
})
weather(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /weatherJSON
The arguments map may contain the following keys:
- east
- north
- south
- west
Each request parameter should be supplied in a map. For example,
Geonames.weather(%{
east: "val",
north: "val",
south: "val",
west: "val"
})
weather_icao(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /weatherIcaoJSON
The arguments map may contain the following keys:
- ICAO
Each request parameter should be supplied in a map. For example,
Geonames.weather_icao(%{
ICAO: "val"
})
wikipedia_bounding_box(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /wikipediaBoundingBoxJSON
The arguments map may contain the following keys:
- east
- maxRows
- north
- south
- west
Each request parameter should be supplied in a map. For example,
Geonames.wikipedia_bounding_box(%{
east: "val",
maxRows: "val",
north: "val",
south: "val",
west: "val"
})
wikipedia_search(args \\ %{})
Specs
Makes a request to the GeoNames endpoint /wikipediaSearchJSON
The arguments map may contain the following keys:
- maxRows
- q
- title
Each request parameter should be supplied in a map. For example,
Geonames.wikipedia_search(%{
maxRows: "val",
q: "val",
title: "val"
})