GeoNames-Elixir v1.0.2 Geonames

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.

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

Functions

astergdem(args \\ %{})

Specs

astergdem(map) :: {Atom.t, 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"
})
children(args \\ %{})

Specs

children(map) :: {Atom.t, 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"
})
cities(args \\ %{})

Specs

cities(map) :: {Atom.t, 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"
})
contains(args \\ %{})

Specs

contains(map) :: {Atom.t, 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"
})
country_code(args \\ %{})

Specs

country_code(map) :: {Atom.t, 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"
})
country_info(args \\ %{})

Specs

country_info(map) :: {Atom.t, 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"
})
country_subdivision(args \\ %{})

Specs

country_subdivision(map) :: {Atom.t, 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"
})
earthquakes(args \\ %{})

Specs

earthquakes(map) :: {Atom.t, 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"
})
find_nearby(args \\ %{})

Specs

find_nearby(map) :: {Atom.t, 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"
})
find_nearby_place_name(args \\ %{})

Specs

find_nearby_place_name(map) :: {Atom.t, 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"
})
find_nearby_pois_osm(args \\ %{})

Specs

find_nearby_pois_osm(map) :: {Atom.t, 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"
})
find_nearby_postal_codes(args \\ %{})

Specs

find_nearby_postal_codes(map) :: {Atom.t, 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"
})
find_nearby_streets(args \\ %{})

Specs

find_nearby_streets(map) :: {Atom.t, 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"
})
find_nearby_streets_osm(args \\ %{})

Specs

find_nearby_streets_osm(map) :: {Atom.t, 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"
})
find_nearby_weather(args \\ %{})

Specs

find_nearby_weather(map) :: {Atom.t, 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"
})
find_nearby_wikipedia(args \\ %{})

Specs

find_nearby_wikipedia(map) :: {Atom.t, 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"
})
find_nearest_address(args \\ %{})

Specs

find_nearest_address(map) :: {Atom.t, 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"
})
find_nearest_intersection(args \\ %{})

Specs

find_nearest_intersection(map) :: {Atom.t, 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"
})
find_nearest_intersection_osm(args \\ %{})

Specs

find_nearest_intersection_osm(map) :: {Atom.t, 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"
})
get(args \\ %{})

Specs

get(map) :: {Atom.t, 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"
})
gtopo30(args \\ %{})

Specs

gtopo30(map) :: {Atom.t, 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"
})
hierarchy(args \\ %{})

Specs

hierarchy(map) :: {Atom.t, 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"
})
neighbourhood(args \\ %{})

Specs

neighbourhood(map) :: {Atom.t, 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"
})
neighbours(args \\ %{})

Specs

neighbours(map) :: {Atom.t, 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"
})
ocean(args \\ %{})

Specs

ocean(map) :: {Atom.t, 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"
})
perform_geonames_request(url)

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

postal_code_country_info(map) :: {Atom.t, 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(%{

})
postal_code_lookup(args \\ %{})

Specs

postal_code_lookup(map) :: {Atom.t, map}

Makes a request to the GeoNames endpoint /postalCodeLookupJSON The arguments map may contain the following keys:

  • postcalcode
  • country
  • maxRows

Each request parameter should be supplied in a map. For example,

Geonames.postal_code_lookup(%{
  postcalcode: "val",
  country: "val",
  maxRows: "val"
})
postal_code_search(args \\ %{})

Specs

postal_code_search(map) :: {Atom.t, 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"
})
search(args \\ %{})

Specs

search(map) :: {Atom.t, 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"
})
siblings(args \\ %{})

Specs

siblings(map) :: {Atom.t, 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"
})
srtm1(args \\ %{})

Specs

srtm1(map) :: {Atom.t, 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"
})
srtm3(args \\ %{})

Specs

srtm3(map) :: {Atom.t, 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"
})
timezone(args \\ %{})

Specs

timezone(map) :: {Atom.t, 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"
})
weather(args \\ %{})

Specs

weather(map) :: {Atom.t, 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"
})
weather_icao(args \\ %{})

Specs

weather_icao(map) :: {Atom.t, 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"
})
wikipedia_bounding_box(args \\ %{})

Specs

wikipedia_bounding_box(map) :: {Atom.t, 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"
})
wikipedia_search(args \\ %{})

Specs

wikipedia_search(map) :: {Atom.t, 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"
})