{"id":22647751,"url":"https://github.com/davidhintelmann/pygeocity","last_synced_at":"2025-07-11T15:34:42.472Z","repository":{"id":190054170,"uuid":"681891645","full_name":"davidhintelmann/pygeocity","owner":"davidhintelmann","description":"This package will reverse geocode i.e., take a latitude and longitude coordinate which will return the country, city name, alternate name(s), population, timezone, and exact coordinates of the city.","archived":false,"fork":false,"pushed_at":"2023-08-25T01:36:16.000Z","size":9535,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-11T21:07:06.929Z","etag":null,"topics":["kdtree","python","reverse-geocode"],"latest_commit_sha":null,"homepage":"","language":"Python","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/davidhintelmann.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,"governance":null}},"created_at":"2023-08-23T01:47:05.000Z","updated_at":"2024-09-10T05:39:49.000Z","dependencies_parsed_at":"2023-08-23T03:16:45.500Z","dependency_job_id":null,"html_url":"https://github.com/davidhintelmann/pygeocity","commit_stats":null,"previous_names":["davidhintelmann/pygeocity"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/davidhintelmann/pygeocity","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidhintelmann%2Fpygeocity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidhintelmann%2Fpygeocity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidhintelmann%2Fpygeocity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidhintelmann%2Fpygeocity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davidhintelmann","download_url":"https://codeload.github.com/davidhintelmann/pygeocity/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidhintelmann%2Fpygeocity/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264841368,"owners_count":23671890,"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":["kdtree","python","reverse-geocode"],"created_at":"2024-12-09T07:34:30.140Z","updated_at":"2025-07-11T15:34:39.916Z","avatar_url":"https://github.com/davidhintelmann.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GeoNames - Find City Name with a Population \u003e 1000\n\n[Opendatasoft](https://public.opendatasoft.com/explore/dataset/geonames-all-cities-with-a-population-1000/table/?disjunctive.cou_name_en\u0026sort=name) has as a dataset from [GeoNames](https://www.geonames.org/about.html) which contains all cities with a population greater than a thousand people. This dataset will be used to create a reverse geocode function, called `search`. This project has been inspired by Richard Penman's [reverse-geocode](https://pypi.org/project/reverse-geocode/) project. Like Richard Penman's approach, I am also using a [k-d tree](https://en.wikipedia.org/wiki/K-d_tree) which is implemented using the [SciPy](https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.KDTree.html) library.\n\nThis package will take a latitude and longitude coordinate which will return the country, city name, alternate name(s), population, timezone, and exact coordinates for that city. \n\n## Dependencies\n  * Python 3.11.4\n  * Numpy 1.25.0\n  * Pandas 2.0.3\n  * SciPy 1.11.1\n\n## Install\n\n    pip install pygeocity\n\nMake sure you install version 0.2.0\n\nUse:\n\n    pip install pygeocity==0.2.0\n\n## Example usage:\n\nThis package only has one function `search` and it has a three parameters: \n- `coordinate` Required - list or list(list)\n  - Search query allows a list of Latitude and Longitude, or a single pair which must be passed as list. It will return name of the nearest city in the same order which the coordinates were passed\n    \n    Example:\n    - single location: coordinates = [11.86, -86.24]\n    - multiple locations: coordinates = [[11.86, -86.24], [42, 49]]\n    \n- `k`: Optional - int \u003e 1, Default: int = 1\n    - Number of of nearest neighbours to find for each set of coordinates. Must be a value greater than zero.\n    \n- `output`: Optional - 'df' or 'dict', default: output = 'df'\n    - Which format to return to users. Either pandas DataFrame or dictionary.\n    \n- `ascending`: Optional - True or False, default: None\n  - If the format should be sorted by ascending, descending population, or no sorting at all. This can help in finding the nearest city with the largest population (might need to increase k).\n\n### Code Examples\n\n- Enter latitude and longitude into the `search` function, as a list, to get your results.\n\n```python\n\u003e\u003e\u003e import geonames\n\u003e\u003e\u003e geonames.search([11.85812, -86.23922], output='dict')\n\nOutputs:\n{'Geoname ID': {0: 3620170},\n 'Name': {0: 'Diriamba'},\n 'ASCII Name': {0: 'Diriamba'},\n 'Alternate Names': {0: 'Diriamba,Diriambo'},\n 'Country Code': {0: 'NI'},\n 'Country name EN': {0: 'Nicaragua'},\n 'Population': {0: 35008},\n 'Timezone': {0: 'America/Managua'},\n 'Modification date': {0: '2018-08-08'},\n 'LABEL EN': {0: 'Nicaragua'},\n 'Coordinates': {0: '11.85812, -86.23922'},\n 'Longitude': {0: '-86.23922'},\n 'Latitude': {0: '11.85812'}}\n```\n\n\n\n- One can also enter a list of multiple latitudes and longitudes into the `search` function to get your results.\n\n```python\n\u003e\u003e\u003e geonames.search([[11.85812, -86.23922],[12.4825, -87.17304]], output='dict')\n\nOutputs:\n{'CoordIndex': {0: 1, 1: 0},\n 'Geoname ID': {0: 3620269, 1: 3620170},\n 'Name': {0: 'Corinto', 1: 'Diriamba'},\n 'ASCII Name': {0: 'Corinto', 1: 'Diriamba'},\n 'Alternate Names': {0: 'Corinto', 1: 'Diriamba,Diriambo'},\n 'Country Code': {0: 'NI', 1: 'NI'},\n 'Country name EN': {0: 'Nicaragua', 1: 'Nicaragua'},\n 'Population': {0: 19183, 1: 35008},\n 'Timezone': {0: 'America/Managua', 1: 'America/Managua'},\n 'Modification date': {0: '2018-08-08', 1: '2018-08-08'},\n 'LABEL EN': {0: 'Nicaragua', 1: 'Nicaragua'},\n 'Coordinates': {0: '12.4825, -87.17304', 1: '11.85812, -86.23922'},\n 'Longitude': {0: '-87.17304', 1: '-86.23922'},\n 'Latitude': {0: '12.4825', 1: '11.85812'}}\n```\n\n- You can also search for more than one nearest neighbour for each Latitude \u0026 Longitude pair entered. Here we search for two nearest neighbours.\n\n```python\n\u003e\u003e\u003e geonames.search([[11.85812, -86.23922],[12.4825, -87.17304]], output='dict', k=2)\n\nOutputs:\n{'CoordIndex': {0: 0, 1: 0, 2: 1, 3: 1},\n 'Geoname ID': {0: 3620163, 1: 3620170, 2: 3619451, 3: 3620269},\n 'Name': {0: 'Dolores', 1: 'Diriamba', 2: 'El Realejo', 3: 'Corinto'},\n 'ASCII Name': {0: 'Dolores', 1: 'Diriamba', 2: 'El Realejo', 3: 'Corinto'},\n 'Alternate Names': {0: 'Dolores',\n  1: 'Diriamba,Diriambo',\n  2: 'El Realejo,Realejo',\n  3: 'Corinto'},\n 'Country Code': {0: 'NI', 1: 'NI', 2: 'NI', 3: 'NI'},\n 'Country name EN': {0: 'Nicaragua',\n  1: 'Nicaragua',\n  2: 'Nicaragua',\n  3: 'Nicaragua'},\n 'Population': {0: 7065, 1: 35008, 2: 6208, 3: 19183},\n 'Timezone': {0: 'America/Managua',\n  1: 'America/Managua',\n  2: 'America/Managua',\n  3: 'America/Managua'},\n 'Modification date': {0: '2018-08-08',\n  1: '2018-08-08',\n  2: '2018-08-08',\n  3: '2018-08-08'},\n 'LABEL EN': {0: 'Nicaragua', 1: 'Nicaragua', 2: 'Nicaragua', 3: 'Nicaragua'},\n 'Coordinates': {0: '11.85672, -86.21552',\n  1: '11.85812, -86.23922',\n  2: '12.54333, -87.16517',\n  3: '12.4825, -87.17304'},\n 'Longitude': {0: '-86.21552', 1: '-86.23922', 2: '-87.16517', 3: '-87.17304'},\n 'Latitude': {0: '11.85672', 1: '11.85812', 2: '12.54333', 3: '12.4825'}}\n```\n\n- You can also search for more than one nearest neighbour for each Latitude \u0026 Longitude pair entered. Here we search for two nearest neighbours, and sort by the cities population in descending order.\n\n```python\n\u003e\u003e\u003e geonames.search([[11.85812, -86.23922],[12.4825, -87.17304]], output='dict', k=2, ascending=False)\n\nOutputs:\n{'CoordIndex': {0: 0, 1: 0, 2: 1, 3: 1},\n 'Geoname ID': {0: 3620170, 1: 3620163, 2: 3620269, 3: 3619451},\n 'Name': {0: 'Diriamba', 1: 'Dolores', 2: 'Corinto', 3: 'El Realejo'},\n 'ASCII Name': {0: 'Diriamba', 1: 'Dolores', 2: 'Corinto', 3: 'El Realejo'},\n 'Alternate Names': {0: 'Diriamba,Diriambo',\n  1: 'Dolores',\n  2: 'Corinto',\n  3: 'El Realejo,Realejo'},\n 'Country Code': {0: 'NI', 1: 'NI', 2: 'NI', 3: 'NI'},\n 'Country name EN': {0: 'Nicaragua',\n  1: 'Nicaragua',\n  2: 'Nicaragua',\n  3: 'Nicaragua'},\n 'Population': {0: 35008, 1: 7065, 2: 19183, 3: 6208},\n 'Timezone': {0: 'America/Managua',\n  1: 'America/Managua',\n  2: 'America/Managua',\n  3: 'America/Managua'},\n 'Modification date': {0: '2018-08-08',\n  1: '2018-08-08',\n  2: '2018-08-08',\n  3: '2018-08-08'},\n 'LABEL EN': {0: 'Nicaragua', 1: 'Nicaragua', 2: 'Nicaragua', 3: 'Nicaragua'},\n 'Coordinates': {0: '11.85812, -86.23922',\n  1: '11.85672, -86.21552',\n  2: '12.4825, -87.17304',\n  3: '12.54333, -87.16517'},\n 'Longitude': {0: '-86.23922', 1: '-86.21552', 2: '-87.17304', 3: '-87.16517'},\n 'Latitude': {0: '11.85812', 1: '11.85672', 2: '12.4825', 3: '12.54333'}}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidhintelmann%2Fpygeocity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidhintelmann%2Fpygeocity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidhintelmann%2Fpygeocity/lists"}