{"id":25762310,"url":"https://github.com/aternus/geonames-client","last_synced_at":"2026-03-12T22:03:10.434Z","repository":{"id":53614722,"uuid":"146309000","full_name":"Aternus/geonames-client","owner":"Aternus","description":"GeoNames API Client","archived":false,"fork":false,"pushed_at":"2024-06-09T21:10:41.000Z","size":361,"stargazers_count":34,"open_issues_count":0,"forks_count":11,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-07-02T19:10:06.300Z","etag":null,"topics":["api","countries","database","geographical","geonames","iso-3166","iso-639-1","languages"],"latest_commit_sha":null,"homepage":null,"language":"PHP","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/Aternus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"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-08-27T14:28:45.000Z","updated_at":"2025-06-14T14:20:32.000Z","dependencies_parsed_at":"2023-12-30T22:28:30.550Z","dependency_job_id":"31f38e29-e2c7-4ecc-8810-ce042345ccbc","html_url":"https://github.com/Aternus/geonames-client","commit_stats":{"total_commits":32,"total_committers":4,"mean_commits":8.0,"dds":0.53125,"last_synced_commit":"fb5c26c62aadff39118a18c4fbadd322aab1602f"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/Aternus/geonames-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aternus%2Fgeonames-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aternus%2Fgeonames-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aternus%2Fgeonames-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aternus%2Fgeonames-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Aternus","download_url":"https://codeload.github.com/Aternus/geonames-client/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aternus%2Fgeonames-client/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264987409,"owners_count":23693824,"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":["api","countries","database","geographical","geonames","iso-3166","iso-639-1","languages"],"created_at":"2025-02-26T19:40:05.403Z","updated_at":"2026-03-12T22:03:10.391Z","avatar_url":"https://github.com/Aternus.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GeoNames Client\n\nA [GeoNames](https://www.geonames.org) API Client for PHP.\n\n[![validate](https://github.com/Aternus/geonames-client/actions/workflows/validate.yml/badge.svg)](https://github.com/Aternus/geonames-client/actions/workflows/validate.yml)\n\nInstall with confidence 🛡️\n\n* Supported OS: Linux, macOS and Windows.\n* Supported PHP versions: 7.2 and up.\n\n- [Quick Start](#quick-start)\n- [Why?](#why)\n- [Installation](#installation)\n- [Other Useful Libraries](#other-useful-libraries)\n- [License](#license)\n- [Credits](#credits)\n\n## Quick Start\n\nAn overview of available API parameters for each endpoint is\n[available here](https://www.geonames.org/export/ws-overview.html).\n\n```php\n\u003c?php\n\nuse GeoNames\\Client as GeoNamesClient;\n\n$g = new GeoNamesClient('username');\n\n// get a list of supported endpoints\n$endpoints = $g-\u003egetSupportedEndpoints();\n\n// get info for country\n// note that I'm using the array destructor introduced in PHP 7.1\n[$country] = $g-\u003ecountryInfo([\n    'country' =\u003e 'IL',\n    'lang'    =\u003e 'ru', // display info in Russian\n]);\n\n// country name (in Russian)\n$country_name = $country-\u003ecountryName;\n\n// spoken languages (ISO-639-1)\n$country_languages = $country-\u003elanguages;\n```\n\n## Client Options\n\nSupported client options:\n\n1. `username`: GeoNames username.\n2. `token`?: GeoNames token (i.e. premium user key).\n3. `api_url`?: URL of the GeoNames web service.\n4. `connect_timeout`?: HTTP Client connection timeout. The number of seconds to\n   wait while trying to connect to a server (default `0`, wait indefinitely).\n5. `fallback_api_url`: COMING SOON.\n6. `fallback_api_url_trigger_count`: COMING SOON.\n\n### Example: Providing options during instantiation\n\n```php\n$g = new GeoNamesClient('username', '', ['api_url' =\u003e 'https://custom-premium.geonames.org']);\n```\n\n### Example: Changing options during runtime\n\n```php\n$g = new GeoNamesClient('username');\n$g-\u003esetOptions(['api_url' =\u003e 'https://custom-premium.geonames.org'])\n```\n\n## Why?\n\nThis library will allow you to get better insights into the world.\n\nAs a developer and a multilingual speaker I've always felt that localization\nwas put on last priority since it was so time-consuming and error-prone.\n\nGetting statistics for each country is a painful process that requires\nunderstanding the different ISO standards, and even then you're still left to\npiece the puzzle together yourself.\n\nLuckily, GeoNames have been collecting statistical data about the world for the\npast few decades and offers that data via their API.\n\nThe aim of this library is to provide a single source of truth for\ncountry [(ISO-3166)](https://en.wikipedia.org/wiki/ISO_3166),\nlanguage [(ISO-639-1)](https://en.wikipedia.org/wiki/ISO_639-1),\nand other locale related statistical data, so that other developers can write\nbetter software which is up-to-date with the latest changes in the world.\n\n## Installation\n\nIf you're using Composer to manage dependencies:\n\n```\ncomposer require aternus/geonames-client\n```\n\nThen, after running `composer update`, you can load the class using Composer's\nautoloading:\n\n```php\nrequire 'vendor/autoload.php';\n```\n\nOtherwise, you can simply require the file directly:\n\n```php\nrequire_once 'vendor/aternus/geonames-client/src/Client.php';\n```\n\nAnd in either case, I'd suggest using an alias.\n\n```php\nuse GeoNames\\Client as GeoNamesClient;\n```\n\n## Other Useful Libraries\n\nPlease make sure to implement some kind of cache mechanism in order to save\nyourself time, bandwidth and be respectful to GeoNames for providing all that\ndata for free.\n\nIf you're making heavy use of the statistical data, you can subscribe to\ntheir [Premium Data](https://www.geonames.org/products/premium-data.html) plan.\n\n## License\n\nReleased under the MIT License - see `LICENSE.md` for details.\n\n## Credits\n\nDavid Jean Louis for the PEAR package which inspired this GeoNames API Client.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faternus%2Fgeonames-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faternus%2Fgeonames-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faternus%2Fgeonames-client/lists"}