Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/pareeohnos/geonames-elixir

An elixir wrapper around the GeoNames API
https://github.com/pareeohnos/geonames-elixir

Last synced: 3 months ago
JSON representation

An elixir wrapper around the GeoNames API

Awesome Lists containing this project

README 

        
[![Build Status](https://travis-ci.org/pareeohnos/geonames-elixir.svg?branch=master)](https://travis-ci.org/pareeohnos/geonames-elixir)



# 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):



  ```elixir

  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:



  ```elixir

    config :geonames, json_library: Jason

  ```



- Ensure geonames is started before your application:



  ```elixir

  def application do

    [applications: [:geonames]]

  end

  ```



## Usage



Usage of GeoNames-Elixir is extremely simple:



  ```elixir

  Geonames.(%{  })

  ```



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](http://www.geonames.org/export/ws-overview.html)

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



  ```elixir

  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.



  ```elixir

  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



  ```elixir

  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.