Geonames

Geonames-Elixir is a simple wrapper around the Geonames.org API. It aims to provide simple access to all available API endpoints that return a JSON result.

Installation

To install GeoNames-Elixir, follow these instructions:

• Add to your list of dependencies in mix.exs geonames-elixir and a JSON decoder library (Jason, Poison or another which supports decode!/1 call):

  def deps do
    [
      { :geonames, "~> 1.0.4" },
      { :poison, "> 3.0.0" }
    ]
  end
  

• (optional) Add to your config a name of the chosen library; if none is set then Poison will be used:

    config :geonames, json_library: Jason
  

• Ensure geonames is started before your application:

  def application do
    [applications: [:geonames]]
  end
  

Usage

Usage of GeoNames-Elixir is extremely simple:

Geonames.<function name>(%{ <parameters> })

Every function accepts a single argument. This is a map containing all of the parameters required for the API call being made. The available option can be found in the documentation using the h function, or by looking through the geonames.org documentation.

Configuration

Before you can use GeoNames-Elixir, you must configure it with your username, base URL (for example, to use with premium plans or your own service) and preferred language. This can be done by simply adding the following to your application configuration

config :geonames,
  username: "demo",
  language: "en",
  base_url: "https://secure.geonames.net"

Alternatively, you can set these with the environment variables

GEONAMES_USERNAME=demo
GEONAMES_LANGUAGE=en
GEONAMES_BASE_URL=https://secure.geonames.net

Note that the language is not required, and will default to en if not set.

Please also not the that language may not effect every API call. It will be supplied for all, however the geonames.org documentation does not specify its usage in every endpoint, so there are no guarantees that your preferred language will be effective.

If :base_url is not specified then "api.geonames.org" will be used by default.

Available functions

GeoNames-Elixir provides the following functions. Each function name maps directly the API provided name for simplicity.

Geonames.astergdem/1
Geonames.children/1
Geonames.cities/1
Geonames.contains/1
Geonames.country_code/1
Geonames.country_info/1
Geonames.country_subdivision/1
Geonames.earthquakes/1
Geonames.find_nearby/1
Geonames.find_nearby_place_name/1
Geonames.find_nearby_postal_codes/1
Geonames.find_nearby_streets/1
Geonames.find_nearby_streets_osm/1
Geonames.find_nearby_weather/1
Geonames.find_nearby_wikipedia/1
Geonames.find_nearby_address/1
Geonames.find_nearby_intersection/1
Geonames.find_nearby_intersection_osm/1
Geonames.get/1
Geonames.gtopo30/1
Geonames.hierarchy/1
Geonames.neighbourhood/1
Geonames.neighbours/1
Geonames.ocean/1
Geonames.postal_code_country_info/1
Geonames.postal_code_lookup/1
Geonames.postal_code_search/1
Geonames.search/1
Geonames.siblings/1
Geonames.srtm1/1
Geonames.srtm3/1
Geonames.timezone/1
Geonames.weather/1
Geonames.weather_icao/1
Geonames.wikipedia_bounding_box/1
Geonames.wikipedia_search/1

If you have an API URL you would like to query directly, then you can use the following function

Geonames.perform_geonames_request(url)

Please note that this function assumes that the response will be JSON. Using the XML endpoints of the API WILL NOT WORK.

Todo

• Add support for the premium API plans
• Write tests

Issues and contributions

Please feel free to use the issue tracker for bugs and requests, but for bugs please provide as much information as possible.

Pull requests are welcomed.

License

GeoNames-Elixir is Licensed under MIT.