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

Link to this function

astergdem(args \\ %{})

Specs

astergdem(map() | keyword()) :: map()

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"
})
Link to this function

children(args \\ %{})

Specs

children(map() | keyword()) :: map()

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"
})
Link to this function

cities(args \\ %{})

Specs

cities(map() | keyword()) :: map()

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"
})
Link to this function

contains(args \\ %{})

Specs

contains(map() | keyword()) :: map()

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"
})
Link to this function

country_code(args \\ %{})

Specs

country_code(map() | keyword()) :: map()

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"
})
Link to this function

country_info(args \\ %{})

Specs

country_info(map() | keyword()) :: map()

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"
})
Link to this function

country_subdivision(args \\ %{})

Specs

country_subdivision(map() | keyword()) :: map()

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"
})
Link to this function

earthquakes(args \\ %{})

Specs

earthquakes(map() | keyword()) :: map()

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"
})
Link to this function

find_nearby(args \\ %{})

Specs

find_nearby(map() | keyword()) :: map()

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"
})
Link to this function

find_nearby_place_name(args \\ %{})

Specs

find_nearby_place_name(map() | keyword()) :: map()

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"
})
Link to this function

find_nearby_pois_osm(args \\ %{})

Specs

find_nearby_pois_osm(map() | keyword()) :: map()

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"
})
Link to this function

find_nearby_postal_codes(args \\ %{})

Specs

find_nearby_postal_codes(map() | keyword()) :: map()

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"
})
Link to this function

find_nearby_streets(args \\ %{})

Specs

find_nearby_streets(map() | keyword()) :: map()

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"
})
Link to this function

find_nearby_streets_osm(args \\ %{})

Specs

find_nearby_streets_osm(map() | keyword()) :: map()

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"
})
Link to this function

find_nearby_weather(args \\ %{})

Specs

find_nearby_weather(map() | keyword()) :: map()

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"
})
Link to this function

find_nearby_wikipedia(args \\ %{})

Specs

find_nearby_wikipedia(map() | keyword()) :: map()

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"
})
Link to this function

find_nearest_address(args \\ %{})

Specs

find_nearest_address(map() | keyword()) :: map()

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"
})
Link to this function

find_nearest_intersection(args \\ %{})

Specs

find_nearest_intersection(map() | keyword()) :: map()

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"
})
Link to this function

find_nearest_intersection_osm(args \\ %{})

Specs

find_nearest_intersection_osm(map() | keyword()) :: map()

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"
})
Link to this function

get(args \\ %{})

Specs

get(map() | keyword()) :: map()

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"
})
Link to this function

gtopo30(args \\ %{})

Specs

gtopo30(map() | keyword()) :: map()

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"
})
Link to this function

hierarchy(args \\ %{})

Specs

hierarchy(map() | keyword()) :: map()

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"
})
Link to this function

neighbourhood(args \\ %{})

Specs

neighbourhood(map() | keyword()) :: map()

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"
})
Link to this function

neighbours(args \\ %{})

Specs

neighbours(map() | keyword()) :: map()

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"
})
Link to this function

ocean(args \\ %{})

Specs

ocean(map() | keyword()) :: map()

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"
})
Link to this function

perform_geonames_request(url)

Specs

perform_geonames_request(String.t()) :: {:ok, map()} | {:error, String.t()}

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.

Link to this function

postal_code_country_info(args \\ %{})

Specs

postal_code_country_info(map() | keyword()) :: map()

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(%{

})
Link to this function

postal_code_lookup(args \\ %{})

Specs

postal_code_lookup(map() | keyword()) :: map()

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"
})
Link to this function

postal_code_search(args \\ %{})

Specs

postal_code_search(map() | keyword()) :: map()

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"
})
Link to this function

search(args \\ %{})

Specs

search(map() | keyword()) :: map()

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"
})
Link to this function

siblings(args \\ %{})

Specs

siblings(map() | keyword()) :: map()

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"
})
Link to this function

srtm1(args \\ %{})

Specs

srtm1(map() | keyword()) :: map()

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"
})
Link to this function

srtm3(args \\ %{})

Specs

srtm3(map() | keyword()) :: map()

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"
})
Link to this function

timezone(args \\ %{})

Specs

timezone(map() | keyword()) :: map()

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"
})
Link to this function

weather(args \\ %{})

Specs

weather(map() | keyword()) :: map()

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"
})
Link to this function

weather_icao(args \\ %{})

Specs

weather_icao(map() | keyword()) :: map()

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"
})
Link to this function

wikipedia_bounding_box(args \\ %{})

Specs

wikipedia_bounding_box(map() | keyword()) :: map()

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"
})
Link to this function

wikipedia_search(args \\ %{})

Specs

wikipedia_search(map() | keyword()) :: map()

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"
})