{"id":20858763,"url":"https://github.com/wakematta/geo_names","last_synced_at":"2025-04-13T06:41:55.028Z","repository":{"id":45527816,"uuid":"158368432","full_name":"WaKeMaTTa/geo_names","owner":"WaKeMaTTa","description":"GeoNames API's wrapper (gem)","archived":false,"fork":false,"pushed_at":"2024-10-24T07:39:05.000Z","size":46,"stargazers_count":18,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-25T03:44:04.529Z","etag":null,"topics":["gem","geonames","ruby","wrapper","wrapper-api"],"latest_commit_sha":null,"homepage":"https://rubygems.org/gems/geo_names","language":"Ruby","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/WaKeMaTTa.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-11-20T10:05:47.000Z","updated_at":"2024-10-24T07:39:06.000Z","dependencies_parsed_at":"2024-10-24T10:29:28.260Z","dependency_job_id":"0bbaa0e7-2959-435d-a326-eb2122403ce0","html_url":"https://github.com/WaKeMaTTa/geo_names","commit_stats":{"total_commits":26,"total_committers":3,"mean_commits":8.666666666666666,"dds":0.07692307692307687,"last_synced_commit":"b0fed3ce7a400a52c6acb93a7309652f2fa338fd"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WaKeMaTTa%2Fgeo_names","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WaKeMaTTa%2Fgeo_names/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WaKeMaTTa%2Fgeo_names/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WaKeMaTTa%2Fgeo_names/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WaKeMaTTa","download_url":"https://codeload.github.com/WaKeMaTTa/geo_names/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248675435,"owners_count":21143763,"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","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":["gem","geonames","ruby","wrapper","wrapper-api"],"created_at":"2024-11-18T04:47:23.160Z","updated_at":"2025-04-13T06:41:55.007Z","avatar_url":"https://github.com/WaKeMaTTa.png","language":"Ruby","readme":"# GeoNames\n\nGeoNames Ruby API Wrapper\n\n[![Build Status](https://travis-ci.org/WaKeMaTTa/geo_names.svg?branch=master)](https://travis-ci.org/WaKeMaTTa/geo_names)\n[![Maintainability](https://api.codeclimate.com/v1/badges/a69ae1a450119061f8e2/maintainability)](https://codeclimate.com/github/WaKeMaTTa/geo_names/maintainability)\n![GitHub](https://img.shields.io/github/license/wakematta/geo_names.svg)\n\nThis gem is a ruby API wrapper for [GeoNames](https://www.geonames.org/) [API's](https://www.geonames.org/export/web-services.html).\n\n## Security\n\nMultifactor authentication:\n\n![Security github.com account](https://img.shields.io/badge/github.com-enabled-brightgreen.svg)\n![Security rubygems.org account](https://img.shields.io/badge/rubygems.org-enabled-brightgreen.svg)\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'geo_names'\n```\n\nAnd then execute:\n\n```bash\n$ bundle\n```\n\nOr install it yourself as:\n\n```bash\n$ gem install geo_names\n```\n\n## Usage\n\n### Pre-requirement\n\nYou need a valid `username` to use the gem. You can get it by signing up [here](http://www.geonames.org/login).\n\nIf you don't set the `username` it will *raises an exception*.\n\n### Configuration\n\nYou can use add initializer for example if you're on Rails.\n\n```ruby\n# config/initializers/geo_names.rb\n\nGeoNames.configure do |config|\n  config.username = ENV['GEONAMES_USERNAME']\nend\n```\n\n### Searching\n\n#### How to search?\n\nFirst you need a `Hash` with the criteria that you want to search.\n\n```ruby\n# example of criteria\ncriteria = {\n  country_code: 'US',\n  name: 'New York',\n  featureClass: %w[P S],\n  maxRows: 1,\n  style: 'short'\n}\n```\n\nThen you can search\n```ruby\nresult = GeoNames::Search.search(criteria)\n```\n\nThe `result` it will be a `Hash` if was successful, like this one:\n```ruby\n{ \"totalResultsCount\" =\u003e 1360,\n  \"geonames\" =\u003e [\n    { \"lng\" =\u003e \"-74.00597\",\n      \"geonameId\" =\u003e 5128581,\n      \"countryCode\" =\u003e \"US\",\n      \"name\" =\u003e \"New York\",\n      \"toponymName\" =\u003e \"New York City\",\n      \"lat\" =\u003e \"40.71427\",\n      \"fcl\" =\u003e \"P\",\n      \"fcode\" =\u003e \"PPL\"\n    }\n  ]\n}\n```\n\nOr if something was wrong it will raise an error of this list:\n```ruby\nGeoNames::AuthorizationExceptionError\nGeoNames::DatabaseTimeoutError\nGeoNames::MissingOrInvalidParameterError\nGeoNames::RecordDoesNotExistError\nGeoNames::OtherError\nGeoNames::NoResultFoundError\nGeoNames::PostalCodeNotFoundError\nGeoNames::DailyLimitOfCreditsExceededError\nGeoNames::HourlyLimitOfCreditsExceededError\nGeoNames::WeeklyLimitOfCreditsExceededError\nGeoNames::InvalidInputError\nGeoNames::ServerOverloadedExceptionError\nGeoNames::ServiceNotImplementedError\nGeoNames::RadiusTooLargeError\nGeoNames::MaxRowsTooLargeError\nGeoNames::StatusCodeNotImplementedError\n```\n\n#### Search engines available\n\n```ruby\nGeoNames::Address\nGeoNames::Astergdem\nGeoNames::Children\nGeoNames::Cities\nGeoNames::Configuration\nGeoNames::Contains\nGeoNames::CountryCode\nGeoNames::CountryInfo\nGeoNames::CountrySubdivision\nGeoNames::Earthquakes\nGeoNames::ExtendedFindNearby\nGeoNames::FindNearByWeather\nGeoNames::FindNearby\nGeoNames::FindNearbyPOIsOSM\nGeoNames::FindNearbyPlaceName\nGeoNames::FindNearbyPostalCodes\nGeoNames::FindNearbyStreets\nGeoNames::FindNearbyStreetsOSM\nGeoNames::FindNearbyWikipedia\nGeoNames::FindNearestAddress\nGeoNames::FindNearestIntersection\nGeoNames::FindNearestIntersectionOSM\nGeoNames::GeoCodeAddress\nGeoNames::Get\nGeoNames::Gtopo30\nGeoNames::Hierarchy\nGeoNames::Neighbourhood\nGeoNames::Neighbours\nGeoNames::Ocean\nGeoNames::PostalCodeCountryInfo\nGeoNames::PostalCodeLookup\nGeoNames::PostalCodeSearch\nGeoNames::Search\nGeoNames::Siblings\nGeoNames::Srtm1\nGeoNames::Srtm3\nGeoNames::Timezone\nGeoNames::Weather\nGeoNames::WeatherIcao\nGeoNames::WikipediaBoundingBox\nGeoNames::WikipediaSearch\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at [geo_names repository](https://github.com/wakematta/geo_names). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the GeoNames project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/geo_names/blob/master/CODE_OF_CONDUCT.md).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwakematta%2Fgeo_names","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwakematta%2Fgeo_names","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwakematta%2Fgeo_names/lists"}