{"id":19850088,"url":"https://github.com/farzai/geonames-php","last_synced_at":"2025-10-24T22:40:29.536Z","repository":{"id":61598095,"uuid":"552957737","full_name":"farzai/geonames-php","owner":"farzai","description":"This package provides a simple way to download Geonames data and format it for friendly use.","archived":false,"fork":false,"pushed_at":"2025-08-11T20:38:28.000Z","size":110,"stargazers_count":1,"open_issues_count":2,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-11T22:16:17.842Z","etag":null,"topics":["countries","country-codes","data","geography","geonames"],"latest_commit_sha":null,"homepage":"","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/farzai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","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,"zenodo":null},"funding":{"github":"parsilver"}},"created_at":"2022-10-17T13:44:37.000Z","updated_at":"2025-08-11T20:38:24.000Z","dependencies_parsed_at":"2023-09-25T01:49:35.372Z","dependency_job_id":"9820b834-8ed1-44a6-991c-16d58297a08a","html_url":"https://github.com/farzai/geonames-php","commit_stats":{"total_commits":20,"total_committers":3,"mean_commits":6.666666666666667,"dds":"0.15000000000000002","last_synced_commit":"beb97ceb64988ef93141aa7a19137e4e69b46e9f"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/farzai/geonames-php","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farzai%2Fgeonames-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farzai%2Fgeonames-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farzai%2Fgeonames-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farzai%2Fgeonames-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/farzai","download_url":"https://codeload.github.com/farzai/geonames-php/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farzai%2Fgeonames-php/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280878345,"owners_count":26406641,"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-24T02:00:06.418Z","response_time":73,"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":["countries","country-codes","data","geography","geonames"],"created_at":"2024-11-12T13:24:17.404Z","updated_at":"2025-10-24T22:40:29.499Z","avatar_url":"https://github.com/farzai.png","language":"PHP","funding_links":["https://github.com/sponsors/parsilver"],"categories":[],"sub_categories":[],"readme":"# Geoname data (PHP)\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/farzai/geonames.svg?style=flat-square)](https://packagist.org/packages/farzai/geonames-php)\n[![Tests](https://img.shields.io/github/actions/workflow/status/farzai/geonames-php/run-tests.yml?branch=main\u0026label=tests\u0026style=flat-square)](https://github.com/farzai/geonames-php/actions/workflows/run-tests.yml)\n[![codecov](https://codecov.io/gh/farzai/geonames-php/branch/main/graph/badge.svg)](https://codecov.io/gh/farzai/geonames-php)\n[![Total Downloads](https://img.shields.io/packagist/dt/farzai/geonames.svg?style=flat-square)](https://packagist.org/packages/farzai/geonames)\nA PHP library for downloading and converting Geonames data. This library provides easy access to both Postal Codes and Gazetteer data from Geonames.\n\n## Features\n\n- Download postal codes data for specific countries or all countries\n- Download detailed geographical data (Gazetteer) including administrative divisions\n- Convert data to JSON format with proper structure\n- Import data directly to MongoDB with proper indexing\n- Memory-efficient processing for large datasets\n- Progress bars for all operations\n- Support for filtering by feature types (for Gazetteer data)\n\n## Installation\n\n```bash\ncomposer require farzai/geonames\n```\n\n## Usage\n\n### Postal Codes\n\nDownload postal codes for a specific country:\n\n```bash\n./bin/geonames geonames:download TH\n```\n\nDownload postal codes for all countries:\n\n```bash\n./bin/geonames geonames:download all\n```\n\nOptions:\n- `--output (-o)`: Output directory (default: ./data)\n- `--format (-f)`: Output format (default: json, options: json, mongodb)\n- `--mongodb-uri`: MongoDB connection URI (default: mongodb://localhost:27017)\n- `--mongodb-db`: MongoDB database name (default: geonames)\n- `--mongodb-collection`: MongoDB collection name (default: postal_codes)\n\nThe postal codes data includes:\n- Country code\n- Postal code\n- Place name\n- Administrative divisions (state/province, county/district, community)\n- Latitude and longitude\n- Accuracy level\n\n### Gazetteer Data\n\nDownload geographical data for a specific country:\n\n```bash\n./bin/geonames geonames:gazetteer:download TH\n```\n\nDownload geographical data for all countries:\n\n```bash\n./bin/geonames geonames:gazetteer:download all\n```\n\nOptions:\n- `--output (-o)`: Output directory (default: ./data)\n- `--format (-f)`: Output format (default: json, options: json, mongodb)\n- `--feature-class (-c)`: Filter by feature class (default: P)\n- `--mongodb-uri`: MongoDB connection URI (default: mongodb://localhost:27017)\n- `--mongodb-db`: MongoDB database name (default: geonames)\n- `--mongodb-collection`: MongoDB collection name (default: gazetteer)\n\nAvailable feature classes:\n- `A`: Country, state, region\n- `H`: Stream, lake\n- `L`: Parks, area\n- `P`: City, village\n- `R`: Road, railroad\n- `S`: Spot, building, farm\n- `T`: Mountain, hill, rock\n- `U`: Undersea\n- `V`: Forest, heath\n\nThe Gazetteer data includes:\n- Geoname ID\n- Name (with ASCII and alternate names)\n- Geographical coordinates\n- Feature class and code\n- Administrative divisions with names\n- Population\n- Elevation\n- Digital elevation model (DEM)\n- Timezone\n- Modification date\n\n## Data Structure\n\n### Postal Codes Structure\n\n#### JSON Format\n\n```json\n{\n    \"country_code\": \"TH\",\n    \"postal_code\": \"10200\",\n    \"place_name\": \"Bang Rak\",\n    \"admin_name1\": \"Bangkok\",\n    \"admin_code1\": \"10\",\n    \"admin_name2\": \"\",\n    \"admin_code2\": \"\",\n    \"admin_name3\": \"\",\n    \"admin_code3\": \"\",\n    \"latitude\": 13.7235,\n    \"longitude\": 100.5147,\n    \"accuracy\": 1\n}\n```\n\n#### MongoDB Format\n\nIn MongoDB, the postal codes data has the same structure as JSON but includes an additional `location` field for geospatial queries:\n\n```json\n{\n    \"country_code\": \"TH\",\n    \"postal_code\": \"10200\",\n    \"place_name\": \"Bang Rak\",\n    \"admin_name1\": \"Bangkok\",\n    \"admin_code1\": \"10\",\n    \"admin_name2\": \"\",\n    \"admin_code2\": \"\",\n    \"admin_name3\": \"\",\n    \"admin_code3\": \"\",\n    \"latitude\": 13.7235,\n    \"longitude\": 100.5147,\n    \"accuracy\": 1,\n    \"location\": {\n        \"type\": \"Point\",\n        \"coordinates\": [100.5147, 13.7235]\n    }\n}\n```\n\nThe MongoDB collection is indexed for efficient queries:\n- Compound index on `country_code` and `postal_code` (unique)\n- Index on `country_code`\n- Index on `postal_code`\n- Geospatial index on `location`\n\n### Gazetteer Structure\n\n#### JSON Format\n\n```json\n{\n    \"geoname_id\": 1609350,\n    \"name\": \"Bangkok\",\n    \"ascii_name\": \"Bangkok\",\n    \"alternate_names\": [\"Krung Thep\", \"กรุงเทพมหานคร\"],\n    \"latitude\": 13.75,\n    \"longitude\": 100.51667,\n    \"feature_class\": \"P\",\n    \"feature_code\": \"PPLC\",\n    \"country_code\": \"TH\",\n    \"cc2\": [],\n    \"admin1_code\": \"40\",\n    \"admin1_name\": \"Bangkok\",\n    \"admin2_code\": \"\",\n    \"admin2_name\": \"\",\n    \"admin3_code\": \"\",\n    \"admin4_code\": \"\",\n    \"population\": 5104476,\n    \"elevation\": 2,\n    \"dem\": 4,\n    \"timezone\": \"Asia/Bangkok\",\n    \"modification_date\": \"2023-01-12\"\n}\n```\n\n#### MongoDB Format\n\nIn MongoDB, the gazetteer data has the same structure as JSON but includes an additional `location` field for geospatial queries:\n\n```json\n{\n    \"geoname_id\": 1609350,\n    \"name\": \"Bangkok\",\n    \"ascii_name\": \"Bangkok\",\n    \"alternate_names\": [\"Krung Thep\", \"กรุงเทพมหานคร\"],\n    \"latitude\": 13.75,\n    \"longitude\": 100.51667,\n    \"location\": {\n        \"type\": \"Point\",\n        \"coordinates\": [100.51667, 13.75]\n    },\n    \"feature_class\": \"P\",\n    \"feature_code\": \"PPLC\",\n    \"country_code\": \"TH\",\n    \"cc2\": [],\n    \"admin1_code\": \"40\",\n    \"admin1_name\": \"Bangkok\",\n    \"admin2_code\": \"\",\n    \"admin2_name\": \"\",\n    \"admin3_code\": \"\",\n    \"admin4_code\": \"\",\n    \"population\": 5104476,\n    \"elevation\": 2,\n    \"dem\": 4,\n    \"timezone\": \"Asia/Bangkok\",\n    \"modification_date\": \"2023-01-12\"\n}\n```\n\nThe MongoDB collection is indexed for efficient queries:\n- Unique index on `geoname_id`\n- Index on `country_code`\n- Index on `feature_class`\n- Index on `feature_code`\n- Text index on `name` and `ascii_name`\n- Geospatial index on `location`\n\n## MongoDB Usage Examples\n\n### Finding locations near a point\n\n```php\n$client = new MongoDB\\Client('mongodb://localhost:27017');\n$collection = $client-\u003egeonames-\u003egazetteer;\n\n// Find all places within 5km of Bangkok\n$result = $collection-\u003efind([\n    'location' =\u003e [\n        '$near' =\u003e [\n            '$geometry' =\u003e [\n                'type' =\u003e 'Point',\n                'coordinates' =\u003e [100.51667, 13.75] // [longitude, latitude]\n            ],\n            '$maxDistance' =\u003e 5000 // 5km in meters\n        ]\n    ]\n]);\n\nforeach ($result as $place) {\n    echo $place['name'] . ' - ' . $place['feature_code'] . PHP_EOL;\n}\n```\n\n### Finding postal codes by country\n\n```php\n$client = new MongoDB\\Client('mongodb://localhost:27017');\n$collection = $client-\u003egeonames-\u003epostal_codes;\n\n// Find all postal codes in Bangkok, Thailand\n$result = $collection-\u003efind([\n    'country_code' =\u003e 'TH',\n    'admin_name1' =\u003e 'Bangkok'\n]);\n\nforeach ($result as $postalCode) {\n    echo $postalCode['postal_code'] . ' - ' . $postalCode['place_name'] . PHP_EOL;\n}\n```\n\n## License\n\nThis package is open-sourced software licensed under the MIT license.\n\n## Credits\n\n- Data provided by [GeoNames](https://www.geonames.org/) under a [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/)\n- Developed by [Parsilver](https://github.com/parsilver)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffarzai%2Fgeonames-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffarzai%2Fgeonames-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffarzai%2Fgeonames-php/lists"}