| Name | area-code-locator JSON |
| Version |
0.2.1
JSON |
| download |
| home_page | None |
| Summary | Reverse-geocode latitude/longitude to NANP (North American) telephone area codes |
| upload_time | 2025-11-04 14:35:37 |
| maintainer | None |
| docs_url | None |
| author | Area Code Locator Contributors |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2025 Your Name
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
area-code
nanp
north-american-numbering-plan
reverse-geocoding
geopandas
gis
geospatial
telephony
python-package
coordinates
latitude-longitude
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
geopandas
shapely
pyproj
pyarrow
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# NANP Area Code Locator
[](https://pypi.org/project/area-code-locator/)
[](https://pypi.org/project/area-code-locator/)
[](LICENSE)
Reverse-geocode latitude/longitude to **NANP** telephone **area codes**. Works offline; ships a compact Parquet of polygons.
---
## ✨ Features
- 🔎 **Reverse-geocode** `(lat, lon)` → area code(s)
- ⚡ **Fast local lookups** (vectorized GeoPandas + spatial index)
- 🪪 **NANP coverage** (US, Canada, participating Caribbean)
- 🧳 **Zero setup** — packaged Parquet data included (~29 MB)
- 🧭 **CRS handled automatically** (WGS84 in / projected out as needed)
- 🧵 **Simple API & CLI** (`lookup()` and `area-code-lookup`)
---
## 📦 Install
```bash
pip install area-code-locator
# From source:
git clone https://github.com/Eat-A-Fish/area-code-locator.git
cd area-code-locator
pip install -e .
```
---
## 🚀 Quickstart
```python
from area_code_locator import lookup, batch_lookup
# Single point (returns all matching/overlay codes by default)
codes = lookup(40.7128, -74.0060) # NYC
print(codes) # -> ['212', '646', '917', ...]
# First/primary only
code = lookup(34.0522, -118.2437, return_all=False) # LA
print(code) # -> '213'
# Batch
points = [(40.7128, -74.0060), (41.8781, -87.6298)]
print(batch_lookup(points)) # -> [['212', ...], ['312', ...]]
```
---
## 🖥️ CLI
```bash
area-code-lookup --lat 40.7128 --lon -74.0060
# -> 917
area-code-lookup --lat 40.7128 --lon -74.0060 --all
# -> ["212", "646", "917", ...]
```
---
## 🧪 API
```python
lookup(lat: float, lon: float, return_all: bool = True) -> Union[str, List[str]]
batch_lookup(points: List[Tuple[float, float]], return_all: bool = True) -> List[Union[str, List[str]]]
```
- `return_all=True` → all matching/overlay area codes
- `return_all=False` → first/primary area code
### Advanced
```python
from area_code_locator import AreaCodeLocator
loc = AreaCodeLocator() # uses bundled data
loc_custom = AreaCodeLocator("path/to/area-codes.parquet")
loc.lookup(40.7128, -74.0060, return_all=True)
```
---
## 🗺️ Data
The package includes a preprocessed Parquet file of area-code polygons, so no setup is required.
### Using your own data:
- Parquet with a polygon geometry column
- An area-code column named one of: `area_code`, `areacode`, `npa`, or `code`
- CRS: EPSG:4326 (WGS84)
---
## 🛠️ Development
```bash
pip install -e ".[dev]"
pytest
```
---
## 🙏 Acknowledgments
Area-code boundaries derived from public NANP datasets (e.g., projects compiling NANP polygons). Thanks to the open geospatial community for GeoPandas/Shapely/PyProj.
---
## 📄 License
MIT © Area Code Locator Contributors
Raw data
{
"_id": null,
"home_page": null,
"name": "area-code-locator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "area-code, nanp, north-american-numbering-plan, reverse-geocoding, geopandas, gis, geospatial, telephony, python-package, coordinates, latitude-longitude",
"author": "Area Code Locator Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/24/47/e5f0a3961996b2c919300bad03972f5c9b9848dddceb81fc8c32baa37c7c/area_code_locator-0.2.1.tar.gz",
"platform": null,
"description": "# NANP Area Code Locator\r\n\r\n[](https://pypi.org/project/area-code-locator/)\r\n[](https://pypi.org/project/area-code-locator/)\r\n[](LICENSE)\r\n\r\nReverse-geocode latitude/longitude to **NANP** telephone **area codes**. Works offline; ships a compact Parquet of polygons.\r\n\r\n---\r\n\r\n## \u2728 Features\r\n- \ud83d\udd0e **Reverse-geocode** `(lat, lon)` \u2192 area code(s)\r\n- \u26a1 **Fast local lookups** (vectorized GeoPandas + spatial index)\r\n- \ud83e\udeaa **NANP coverage** (US, Canada, participating Caribbean)\r\n- \ud83e\uddf3 **Zero setup** \u2014 packaged Parquet data included (~29 MB)\r\n- \ud83e\udded **CRS handled automatically** (WGS84 in / projected out as needed)\r\n- \ud83e\uddf5 **Simple API & CLI** (`lookup()` and `area-code-lookup`)\r\n\r\n---\r\n\r\n## \ud83d\udce6 Install\r\n\r\n```bash\r\npip install area-code-locator\r\n\r\n# From source:\r\ngit clone https://github.com/Eat-A-Fish/area-code-locator.git\r\ncd area-code-locator\r\npip install -e .\r\n```\r\n\r\n---\r\n\r\n## \ud83d\ude80 Quickstart\r\n\r\n```python\r\nfrom area_code_locator import lookup, batch_lookup\r\n\r\n# Single point (returns all matching/overlay codes by default)\r\ncodes = lookup(40.7128, -74.0060) # NYC\r\nprint(codes) # -> ['212', '646', '917', ...]\r\n\r\n# First/primary only\r\ncode = lookup(34.0522, -118.2437, return_all=False) # LA\r\nprint(code) # -> '213'\r\n\r\n# Batch\r\npoints = [(40.7128, -74.0060), (41.8781, -87.6298)]\r\nprint(batch_lookup(points)) # -> [['212', ...], ['312', ...]]\r\n```\r\n\r\n---\r\n\r\n## \ud83d\udda5\ufe0f CLI\r\n\r\n```bash\r\narea-code-lookup --lat 40.7128 --lon -74.0060\r\n# -> 917\r\n\r\narea-code-lookup --lat 40.7128 --lon -74.0060 --all\r\n# -> [\"212\", \"646\", \"917\", ...]\r\n```\r\n\r\n---\r\n\r\n## \ud83e\uddea API\r\n\r\n```python\r\nlookup(lat: float, lon: float, return_all: bool = True) -> Union[str, List[str]]\r\nbatch_lookup(points: List[Tuple[float, float]], return_all: bool = True) -> List[Union[str, List[str]]]\r\n```\r\n\r\n- `return_all=True` \u2192 all matching/overlay area codes\r\n- `return_all=False` \u2192 first/primary area code\r\n\r\n### Advanced\r\n\r\n```python\r\nfrom area_code_locator import AreaCodeLocator\r\n\r\nloc = AreaCodeLocator() # uses bundled data\r\nloc_custom = AreaCodeLocator(\"path/to/area-codes.parquet\")\r\nloc.lookup(40.7128, -74.0060, return_all=True)\r\n```\r\n\r\n---\r\n\r\n## \ud83d\uddfa\ufe0f Data\r\n\r\nThe package includes a preprocessed Parquet file of area-code polygons, so no setup is required.\r\n\r\n### Using your own data:\r\n- Parquet with a polygon geometry column\r\n- An area-code column named one of: `area_code`, `areacode`, `npa`, or `code`\r\n- CRS: EPSG:4326 (WGS84)\r\n\r\n---\r\n\r\n## \ud83d\udee0\ufe0f Development\r\n\r\n```bash\r\npip install -e \".[dev]\"\r\npytest\r\n```\r\n\r\n---\r\n\r\n## \ud83d\ude4f Acknowledgments\r\n\r\nArea-code boundaries derived from public NANP datasets (e.g., projects compiling NANP polygons). Thanks to the open geospatial community for GeoPandas/Shapely/PyProj.\r\n\r\n---\r\n\r\n## \ud83d\udcc4 License\r\n\r\nMIT \u00a9 Area Code Locator Contributors\r\n",
"bugtrack_url": null,
"license": "MIT License\r\n \r\n Copyright (c) 2025 Your Name\r\n \r\n Permission is hereby granted, free of charge, to any person obtaining a copy\r\n of this software and associated documentation files (the \"Software\"), to deal\r\n in the Software without restriction, including without limitation the rights\r\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r\n copies of the Software, and to permit persons to whom the Software is\r\n furnished to do so, subject to the following conditions:\r\n \r\n The above copyright notice and this permission notice shall be included in all\r\n copies or substantial portions of the Software.\r\n \r\n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r\n SOFTWARE.",
"summary": "Reverse-geocode latitude/longitude to NANP (North American) telephone area codes",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/Eat-A-Fish/area-code-locator",
"Issues": "https://github.com/Eat-A-Fish/area-code-locator/issues",
"Repository": "https://github.com/Eat-A-Fish/area-code-locator"
},
"split_keywords": [
"area-code",
" nanp",
" north-american-numbering-plan",
" reverse-geocoding",
" geopandas",
" gis",
" geospatial",
" telephony",
" python-package",
" coordinates",
" latitude-longitude"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a95dc21661a63d2c66c84cb837e69342b97f4df3eb31b9fe4283d8b6049bc2e2",
"md5": "9dfc60ea7094757e27b03441f3e54157",
"sha256": "f2c54c2dc29e98653104f64aa92d4c7f1ece33a6ab85cd67c84207587c151ecb"
},
"downloads": -1,
"filename": "area_code_locator-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9dfc60ea7094757e27b03441f3e54157",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 23112648,
"upload_time": "2025-11-04T14:35:30",
"upload_time_iso_8601": "2025-11-04T14:35:30.667458Z",
"url": "https://files.pythonhosted.org/packages/a9/5d/c21661a63d2c66c84cb837e69342b97f4df3eb31b9fe4283d8b6049bc2e2/area_code_locator-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2447e5f0a3961996b2c919300bad03972f5c9b9848dddceb81fc8c32baa37c7c",
"md5": "e46614e175eddf3bbf4ce5eb3bec20cb",
"sha256": "e01c3a9ad02074e3db63ec6fd42b32d3b515391dcc84c6d5298ecba4857e8f21"
},
"downloads": -1,
"filename": "area_code_locator-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "e46614e175eddf3bbf4ce5eb3bec20cb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 23118350,
"upload_time": "2025-11-04T14:35:37",
"upload_time_iso_8601": "2025-11-04T14:35:37.095479Z",
"url": "https://files.pythonhosted.org/packages/24/47/e5f0a3961996b2c919300bad03972f5c9b9848dddceb81fc8c32baa37c7c/area_code_locator-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-04 14:35:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Eat-A-Fish",
"github_project": "area-code-locator",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "geopandas",
"specs": [
[
">=",
"0.13.0"
]
]
},
{
"name": "shapely",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "pyproj",
"specs": [
[
">=",
"3.4.0"
]
]
},
{
"name": "pyarrow",
"specs": [
[
">=",
"10.0.0"
]
]
}
],
"lcname": "area-code-locator"
}
