{"id":13508244,"url":"https://github.com/pareeohnos/geonames-elixir","last_synced_at":"2025-10-21T17:43:43.585Z","repository":{"id":10224055,"uuid":"64952749","full_name":"pareeohnos/geonames-elixir","owner":"pareeohnos","description":"An elixir wrapper around the GeoNames API","archived":false,"fork":false,"pushed_at":"2022-08-10T08:27:50.000Z","size":53,"stargazers_count":24,"open_issues_count":0,"forks_count":7,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-19T06:20:42.967Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pareeohnos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-08-04T17:07:00.000Z","updated_at":"2025-06-17T15:43:01.000Z","dependencies_parsed_at":"2022-08-04T15:15:29.894Z","dependency_job_id":null,"html_url":"https://github.com/pareeohnos/geonames-elixir","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/pareeohnos/geonames-elixir","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pareeohnos%2Fgeonames-elixir","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pareeohnos%2Fgeonames-elixir/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pareeohnos%2Fgeonames-elixir/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pareeohnos%2Fgeonames-elixir/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pareeohnos","download_url":"https://codeload.github.com/pareeohnos/geonames-elixir/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pareeohnos%2Fgeonames-elixir/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280304898,"owners_count":26308066,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-21T02:00:06.614Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T02:00:50.300Z","updated_at":"2025-10-21T17:43:43.551Z","avatar_url":"https://github.com/pareeohnos.png","language":"Elixir","funding_links":[],"categories":["Geolocation"],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/pareeohnos/geonames-elixir.svg?branch=master)](https://travis-ci.org/pareeohnos/geonames-elixir)\n\n# Geonames\n\nGeonames-Elixir is a simple wrapper around the Geonames.org API. It aims to provide\nsimple access to all available API endpoints that return a JSON result.\n\n## Installation\n\nTo install GeoNames-Elixir, follow these instructions:\n\n- 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):\n\n  ```elixir\n  def deps do\n    [\n      { :geonames, \"~\u003e 1.0.4\" },\n      { :poison, \"\u003e 3.0.0\" }\n    ]\n  end\n  ```\n- (optional) Add to your config a name of the chosen library; if none is set then Poison will be used:\n\n  ```elixir\n    config :geonames, json_library: Jason\n  ```\n\n- Ensure geonames is started before your application:\n\n  ```elixir\n  def application do\n    [applications: [:geonames]]\n  end\n  ```\n\n\n## Usage\n\nUsage of GeoNames-Elixir is extremely simple:\n\n  ```elixir\n  Geonames.\u003cfunction name\u003e(%{ \u003cparameters\u003e })\n  ```\n\nEvery function accepts a single argument. This is a map containing\nall of the parameters required for the API call being made. The\navailable option can be found in the documentation using the `h`\nfunction, or by looking through the [geonames.org](http://www.geonames.org/export/ws-overview.html)\ndocumentation.\n\n\n## Configuration\n\nBefore you can use GeoNames-Elixir, you must configure it with your\nusername, base URL (for example, to use with premium plans or your own service) \nand preferred language. This can be done by simply adding the following \nto your application configuration\n\n  ```elixir\n  config :geonames,\n    username: \"demo\",\n    language: \"en\",\n    base_url: \"https://secure.geonames.net\"\n  ```\n\nAlternatively, you can set these with the environment variables\n\n  ```\n  GEONAMES_USERNAME=demo\n  GEONAMES_LANGUAGE=en\n  GEONAMES_BASE_URL=https://secure.geonames.net\n  ```\n\nNote that the language is not required, and will default to `en`\nif not set.\n\nPlease also not the that language may not effect every API call.\nIt will be supplied for all, however the geonames.org documentation\ndoes not specify its usage in every endpoint, so there are no\nguarantees that your preferred language will be effective.\n\nIf `:base_url` is not specified then `\"api.geonames.org\"` will be used by default.\n\n\n## Available functions\n\nGeoNames-Elixir provides the following functions. Each function\nname maps directly the API provided name for simplicity.\n\n  ```elixir\n  Geonames.astergdem/1\n  Geonames.children/1\n  Geonames.cities/1\n  Geonames.contains/1\n  Geonames.country_code/1\n  Geonames.country_info/1\n  Geonames.country_subdivision/1\n  Geonames.earthquakes/1\n  Geonames.find_nearby/1\n  Geonames.find_nearby_place_name/1\n  Geonames.find_nearby_postal_codes/1\n  Geonames.find_nearby_streets/1\n  Geonames.find_nearby_streets_osm/1\n  Geonames.find_nearby_weather/1\n  Geonames.find_nearby_wikipedia/1\n  Geonames.find_nearby_address/1\n  Geonames.find_nearby_intersection/1\n  Geonames.find_nearby_intersection_osm/1\n  Geonames.get/1\n  Geonames.gtopo30/1\n  Geonames.hierarchy/1\n  Geonames.neighbourhood/1\n  Geonames.neighbours/1\n  Geonames.ocean/1\n  Geonames.postal_code_country_info/1\n  Geonames.postal_code_lookup/1\n  Geonames.postal_code_search/1\n  Geonames.search/1\n  Geonames.siblings/1\n  Geonames.srtm1/1\n  Geonames.srtm3/1\n  Geonames.timezone/1\n  Geonames.weather/1\n  Geonames.weather_icao/1\n  Geonames.wikipedia_bounding_box/1\n  Geonames.wikipedia_search/1\n  ```\n\nIf you have an API URL you would like to query directly, then you\ncan use the following function\n\n  ```elixir\n  Geonames.perform_geonames_request(url)\n  ```\n\nPlease note that this function assumes that the response will be\nJSON. Using the XML endpoints of the API WILL NOT WORK.\n\n\n## Todo\n\n- Add support for the premium API plans\n- Write tests\n\n## Issues and contributions\n\nPlease feel free to use the issue tracker for bugs and requests, but for bugs\nplease provide as much information as possible.\n\nPull requests are welcomed.\n\n## License\n\nGeoNames-Elixir is Licensed under MIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpareeohnos%2Fgeonames-elixir","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpareeohnos%2Fgeonames-elixir","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpareeohnos%2Fgeonames-elixir/lists"}