# UKPostCodeIO Python Library
[](LICENSE)
## Introduction
UKPostCodeIO is a Python client library for the [Postcodes.io](https://postcodes.io/) API, a free and open-source UK postcode lookup and geocoder. This library provides convenient access to the Postcodes.io API endpoints, allowing developers to integrate postcode data and geolocation services into their Python applications seamlessly.
## Features
- **Postcode Lookup**: Retrieve detailed information about a specific postcode.
- **Bulk Postcode Lookup**: Lookup multiple postcodes in a single request.
- **Reverse Geocoding**: Find nearest postcodes to given coordinates.
- **Bulk Reverse Geocoding**: Reverse geocode multiple coordinates.
- **Postcode Validation**: Validate the format and existence of a postcode.
- **Autocomplete**: Get postcode suggestions based on partial input.
- **Random Postcode**: Retrieve a random postcode.
- **Outcode Services**: Lookup and reverse geocode outcodes (the first part of a postcode).
- **Scottish Postcode Lookup**: Access data specific to Scottish postcodes.
- **Terminated Postcode Lookup**: Retrieve information on terminated postcodes.
- **Place Services**: Lookup and query places by code or name.
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Initializing the Client](#initializing-the-client)
- [Lookup Postcode](#lookup-postcode)
- [Bulk Lookup Postcodes](#bulk-lookup-postcodes)
- [Reverse Geocode](#reverse-geocode)
- [Bulk Reverse Geocode](#bulk-reverse-geocode)
- [Postcode Validation](#postcode-validation)
- [Nearest Postcodes](#nearest-postcodes)
- [Autocomplete Postcode](#autocomplete-postcode)
- [Random Postcode](#random-postcode)
- [Outcode Services](#outcode-services)
- [Scottish Postcode Lookup](#scottish-postcode-lookup)
- [Terminated Postcode Lookup](#terminated-postcode-lookup)
- [Place Services](#place-services)
- [Error Handling](#error-handling)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#acknowledgments)
## Installation
Install the library using pip:
```bash
pip install ukpostcodeio
```
*Note: Replace `ukpostcodeio` with the actual package name if it's different when published to PyPI.*
Alternatively, you can install it directly from the source:
```bash
git clone https://github.com/ymrohit/ukpostcodeio.git
cd ukpostcodeio
pip install .
```
## Usage
### Initializing the Client
```python
from ukpostcodeio.client import UKPostCodeIO
# Initialize the client with default settings
postcode_client = UKPostCodeIO()
# Initialize the client with custom timeout and retries
postcode_client = UKPostCodeIO(timeout=10, max_retries=5)
```
### Lookup Postcode
Retrieve information about a specific postcode.
```python
result = postcode_client.lookup_postcode("SW1A 1AA")
print(result)
```
### Bulk Lookup Postcodes
Lookup multiple postcodes in a single request.
```python
postcodes = ["SW1A 1AA", "EC1A 1BB", "W1A 0AX"]
results = postcode_client.bulk_lookup_postcodes(postcodes)
print(results)
```
### Reverse Geocode
Find the nearest postcodes to a given longitude and latitude.
```python
longitude = -0.1278 # Longitude for London
latitude = 51.5074 # Latitude for London
results = postcode_client.reverse_geocode(longitude, latitude)
print(results)
```
### Bulk Reverse Geocode
Reverse geocode multiple coordinates.
```python
geolocations = [
{"longitude": -0.1278, "latitude": 51.5074},
{"longitude": -0.1425, "latitude": 51.5010}
]
results = postcode_client.bulk_reverse_geocode(geolocations)
print(results)
```
### Postcode Validation
Check if a postcode is valid.
```python
is_valid = postcode_client.validate_postcode("SW1A 1AA")
print(is_valid) # True
is_valid = postcode_client.validate_postcode("INVALID")
print(is_valid) # False
```
### Nearest Postcodes
Find the nearest postcodes to a given postcode.
```python
results = postcode_client.nearest_postcodes("SW1A 1AA")
print(results)
```
### Autocomplete Postcode
Get postcode suggestions based on partial input.
```python
suggestions = postcode_client.autocomplete_postcode("SW1A")
print(suggestions)
```
### Random Postcode
Retrieve a random postcode.
```python
random_postcode = postcode_client.random_postcode()
print(random_postcode)
# Retrieve a random postcode within a specific outcode
random_postcode = postcode_client.random_postcode(outcode="SW1A")
print(random_postcode)
```
### Outcode Services
#### Lookup Outcode
Get information about an outcode.
```python
outcode_info = postcode_client.lookup_outcode("SW1A")
print(outcode_info)
```
#### Reverse Geocode Outcode
Find the nearest outcodes to given coordinates.
```python
results = postcode_client.reverse_geocode_outcode(-0.1278, 51.5074)
print(results)
```
#### Nearest Outcodes
Find the nearest outcodes to a given outcode.
```python
results = postcode_client.nearest_outcodes("SW1A")
print(results)
```
### Scottish Postcode Lookup
Retrieve data specific to a Scottish postcode.
```python
scottish_data = postcode_client.scottish_postcode_lookup("EH1 1YZ")
print(scottish_data)
```
### Terminated Postcode Lookup
Get information about a terminated postcode.
```python
terminated_postcode_info = postcode_client.terminated_postcode_lookup("EX16 5BL")
print(terminated_postcode_info)
```
### Place Services
#### Lookup Place
Find a place by its code.
```python
place_info = postcode_client.lookup_place("osgb4000000074564391")
print(place_info)
```
#### Query Place
Search for places by name.
```python
places = postcode_client.query_place("London")
print(places)
```
#### Random Place
Retrieve a random place.
```python
random_place = postcode_client.random_place()
print(random_place)
```
### Closing the Client
It's good practice to close the client session when done.
```python
postcode_client.close()
```
Or use it as a context manager:
```python
with UKPostCodeIO() as postcode_client:
result = postcode_client.lookup_postcode("SW1A 1AA")
print(result)
```
## Error Handling
The library defines custom exceptions to help handle different error scenarios:
- **PostcodesIOError**: Base exception class for all Postcodes.io errors.
- **PostcodesIOHTTPError**: Raised for HTTP errors (e.g., 404 Not Found, 500 Internal Server Error).
- **PostcodesIOTimeoutError**: Raised when a request times out.
- **PostcodesIOValidationError**: Raised for validation errors.
- **PostcodesIONetworkError**: Raised for network-related errors (e.g., connection errors).
### Handling Exceptions
```python
from ukpostcodeio.exceptions import (
PostcodesIOError,
PostcodesIOHTTPError,
PostcodesIOTimeoutError,
PostcodesIONetworkError
)
try:
result = postcode_client.lookup_postcode("INVALID")
except PostcodesIOHTTPError as e:
print(f"HTTP Error: {e.status_code} - {e.error_message}")
except PostcodesIOTimeoutError:
print("The request timed out.")
except PostcodesIONetworkError:
print("A network error occurred.")
except PostcodesIOError as e:
print(f"An error occurred: {e}")
```
### Common Error Scenarios
- **Invalid Postcode**: Raises `PostcodesIOHTTPError` with a 404 status code.
- **Network Issues**: Raises `PostcodesIONetworkError` if there's a connection problem.
- **Timeouts**: Raises `PostcodesIOTimeoutError` if the request exceeds the specified timeout.
- **Invalid Parameters**: Raises `PostcodesIOValidationError` if parameters are invalid.
## Testing
The library includes a suite of unit tests to ensure functionality.
### Running Tests
1. Install the testing dependencies:
```bash
pip install -r requirements-dev.txt
```
2. Run the tests:
```bash
python -m unittest discover Tests
```
*Note: Ensure that you have network connectivity when running the tests, as they make real API calls.*
## Contributing
Contributions are welcome! Please follow these steps:
1. Fork the repository.
2. Create a new branch: `git checkout -b feature/your-feature-name`.
3. Make your changes and commit them: `git commit -m 'Add some feature'`.
4. Push to the branch: `git push origin feature/your-feature-name`.
5. Submit a pull request.
Please ensure your code passes all tests and adheres to the project's coding standards.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- This library utilizes the [Postcodes.io](https://postcodes.io/) API, an open-source project that provides UK postcode data and geolocation services.
- Special thanks to the Postcodes.io team for their comprehensive API and open data initiatives.
## Additional Notes
- **Rate Limiting**: Postcodes.io does not enforce rate limiting, but it's good practice to implement it on your side if you're making a large number of requests.
- **Data Accuracy**: While the data is regularly updated, always cross-reference critical data with official sources.
- **API Changes**: The library is designed to handle the current API endpoints. Keep an eye on the [Postcodes.io documentation](https://postcodes.io/docs) for any changes.
---
For any issues or questions, please open an issue on the GitHub repository.
Raw data
{
"_id": null,
"home_page": "https://github.com/ymrohit/ukpostcodeio",
"name": "ukpostcodeio",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "postcode, uk, postcodes.io, api, client",
"author": "Rohit Yelukati Mahendra",
"author_email": "Rohit Yelukati Mahendra <rohityelukati@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/82/d8/42abd93bc344884ba51b3dbff0e4d561747722599aa1539091a0a40d1a22/ukpostcodeio-1.0.0.tar.gz",
"platform": null,
"description": "# UKPostCodeIO Python Library\n\n[](LICENSE)\n\n## Introduction\n\nUKPostCodeIO is a Python client library for the [Postcodes.io](https://postcodes.io/) API, a free and open-source UK postcode lookup and geocoder. This library provides convenient access to the Postcodes.io API endpoints, allowing developers to integrate postcode data and geolocation services into their Python applications seamlessly.\n\n## Features\n\n- **Postcode Lookup**: Retrieve detailed information about a specific postcode.\n- **Bulk Postcode Lookup**: Lookup multiple postcodes in a single request.\n- **Reverse Geocoding**: Find nearest postcodes to given coordinates.\n- **Bulk Reverse Geocoding**: Reverse geocode multiple coordinates.\n- **Postcode Validation**: Validate the format and existence of a postcode.\n- **Autocomplete**: Get postcode suggestions based on partial input.\n- **Random Postcode**: Retrieve a random postcode.\n- **Outcode Services**: Lookup and reverse geocode outcodes (the first part of a postcode).\n- **Scottish Postcode Lookup**: Access data specific to Scottish postcodes.\n- **Terminated Postcode Lookup**: Retrieve information on terminated postcodes.\n- **Place Services**: Lookup and query places by code or name.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n - [Initializing the Client](#initializing-the-client)\n - [Lookup Postcode](#lookup-postcode)\n - [Bulk Lookup Postcodes](#bulk-lookup-postcodes)\n - [Reverse Geocode](#reverse-geocode)\n - [Bulk Reverse Geocode](#bulk-reverse-geocode)\n - [Postcode Validation](#postcode-validation)\n - [Nearest Postcodes](#nearest-postcodes)\n - [Autocomplete Postcode](#autocomplete-postcode)\n - [Random Postcode](#random-postcode)\n - [Outcode Services](#outcode-services)\n - [Scottish Postcode Lookup](#scottish-postcode-lookup)\n - [Terminated Postcode Lookup](#terminated-postcode-lookup)\n - [Place Services](#place-services)\n- [Error Handling](#error-handling)\n- [Testing](#testing)\n- [Contributing](#contributing)\n- [License](#license)\n- [Acknowledgments](#acknowledgments)\n\n## Installation\n\nInstall the library using pip:\n\n```bash\npip install ukpostcodeio\n```\n\n*Note: Replace `ukpostcodeio` with the actual package name if it's different when published to PyPI.*\n\nAlternatively, you can install it directly from the source:\n\n```bash\ngit clone https://github.com/ymrohit/ukpostcodeio.git\ncd ukpostcodeio\npip install .\n```\n\n## Usage\n\n### Initializing the Client\n\n```python\nfrom ukpostcodeio.client import UKPostCodeIO\n\n# Initialize the client with default settings\npostcode_client = UKPostCodeIO()\n\n# Initialize the client with custom timeout and retries\npostcode_client = UKPostCodeIO(timeout=10, max_retries=5)\n```\n\n### Lookup Postcode\n\nRetrieve information about a specific postcode.\n\n```python\nresult = postcode_client.lookup_postcode(\"SW1A 1AA\")\nprint(result)\n```\n\n### Bulk Lookup Postcodes\n\nLookup multiple postcodes in a single request.\n\n```python\npostcodes = [\"SW1A 1AA\", \"EC1A 1BB\", \"W1A 0AX\"]\nresults = postcode_client.bulk_lookup_postcodes(postcodes)\nprint(results)\n```\n\n### Reverse Geocode\n\nFind the nearest postcodes to a given longitude and latitude.\n\n```python\nlongitude = -0.1278 # Longitude for London\nlatitude = 51.5074 # Latitude for London\n\nresults = postcode_client.reverse_geocode(longitude, latitude)\nprint(results)\n```\n\n### Bulk Reverse Geocode\n\nReverse geocode multiple coordinates.\n\n```python\ngeolocations = [\n {\"longitude\": -0.1278, \"latitude\": 51.5074},\n {\"longitude\": -0.1425, \"latitude\": 51.5010}\n]\n\nresults = postcode_client.bulk_reverse_geocode(geolocations)\nprint(results)\n```\n\n### Postcode Validation\n\nCheck if a postcode is valid.\n\n```python\nis_valid = postcode_client.validate_postcode(\"SW1A 1AA\")\nprint(is_valid) # True\n\nis_valid = postcode_client.validate_postcode(\"INVALID\")\nprint(is_valid) # False\n```\n\n### Nearest Postcodes\n\nFind the nearest postcodes to a given postcode.\n\n```python\nresults = postcode_client.nearest_postcodes(\"SW1A 1AA\")\nprint(results)\n```\n\n### Autocomplete Postcode\n\nGet postcode suggestions based on partial input.\n\n```python\nsuggestions = postcode_client.autocomplete_postcode(\"SW1A\")\nprint(suggestions)\n```\n\n### Random Postcode\n\nRetrieve a random postcode.\n\n```python\nrandom_postcode = postcode_client.random_postcode()\nprint(random_postcode)\n\n# Retrieve a random postcode within a specific outcode\nrandom_postcode = postcode_client.random_postcode(outcode=\"SW1A\")\nprint(random_postcode)\n```\n\n### Outcode Services\n\n#### Lookup Outcode\n\nGet information about an outcode.\n\n```python\noutcode_info = postcode_client.lookup_outcode(\"SW1A\")\nprint(outcode_info)\n```\n\n#### Reverse Geocode Outcode\n\nFind the nearest outcodes to given coordinates.\n\n```python\nresults = postcode_client.reverse_geocode_outcode(-0.1278, 51.5074)\nprint(results)\n```\n\n#### Nearest Outcodes\n\nFind the nearest outcodes to a given outcode.\n\n```python\nresults = postcode_client.nearest_outcodes(\"SW1A\")\nprint(results)\n```\n\n### Scottish Postcode Lookup\n\nRetrieve data specific to a Scottish postcode.\n\n```python\nscottish_data = postcode_client.scottish_postcode_lookup(\"EH1 1YZ\")\nprint(scottish_data)\n```\n\n### Terminated Postcode Lookup\n\nGet information about a terminated postcode.\n\n```python\nterminated_postcode_info = postcode_client.terminated_postcode_lookup(\"EX16 5BL\")\nprint(terminated_postcode_info)\n```\n\n### Place Services\n\n#### Lookup Place\n\nFind a place by its code.\n\n```python\nplace_info = postcode_client.lookup_place(\"osgb4000000074564391\")\nprint(place_info)\n```\n\n#### Query Place\n\nSearch for places by name.\n\n```python\nplaces = postcode_client.query_place(\"London\")\nprint(places)\n```\n\n#### Random Place\n\nRetrieve a random place.\n\n```python\nrandom_place = postcode_client.random_place()\nprint(random_place)\n```\n\n### Closing the Client\n\nIt's good practice to close the client session when done.\n\n```python\npostcode_client.close()\n```\n\nOr use it as a context manager:\n\n```python\nwith UKPostCodeIO() as postcode_client:\n result = postcode_client.lookup_postcode(\"SW1A 1AA\")\n print(result)\n```\n\n## Error Handling\n\nThe library defines custom exceptions to help handle different error scenarios:\n\n- **PostcodesIOError**: Base exception class for all Postcodes.io errors.\n- **PostcodesIOHTTPError**: Raised for HTTP errors (e.g., 404 Not Found, 500 Internal Server Error).\n- **PostcodesIOTimeoutError**: Raised when a request times out.\n- **PostcodesIOValidationError**: Raised for validation errors.\n- **PostcodesIONetworkError**: Raised for network-related errors (e.g., connection errors).\n\n### Handling Exceptions\n\n```python\nfrom ukpostcodeio.exceptions import (\n PostcodesIOError,\n PostcodesIOHTTPError,\n PostcodesIOTimeoutError,\n PostcodesIONetworkError\n)\n\ntry:\n result = postcode_client.lookup_postcode(\"INVALID\")\nexcept PostcodesIOHTTPError as e:\n print(f\"HTTP Error: {e.status_code} - {e.error_message}\")\nexcept PostcodesIOTimeoutError:\n print(\"The request timed out.\")\nexcept PostcodesIONetworkError:\n print(\"A network error occurred.\")\nexcept PostcodesIOError as e:\n print(f\"An error occurred: {e}\")\n```\n\n### Common Error Scenarios\n\n- **Invalid Postcode**: Raises `PostcodesIOHTTPError` with a 404 status code.\n- **Network Issues**: Raises `PostcodesIONetworkError` if there's a connection problem.\n- **Timeouts**: Raises `PostcodesIOTimeoutError` if the request exceeds the specified timeout.\n- **Invalid Parameters**: Raises `PostcodesIOValidationError` if parameters are invalid.\n\n## Testing\n\nThe library includes a suite of unit tests to ensure functionality.\n\n### Running Tests\n\n1. Install the testing dependencies:\n\n```bash\npip install -r requirements-dev.txt\n```\n\n2. Run the tests:\n\n```bash\npython -m unittest discover Tests\n```\n\n*Note: Ensure that you have network connectivity when running the tests, as they make real API calls.*\n\n## Contributing\n\nContributions are welcome! Please follow these steps:\n\n1. Fork the repository.\n2. Create a new branch: `git checkout -b feature/your-feature-name`.\n3. Make your changes and commit them: `git commit -m 'Add some feature'`.\n4. Push to the branch: `git push origin feature/your-feature-name`.\n5. Submit a pull request.\n\nPlease ensure your code passes all tests and adheres to the project's coding standards.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- This library utilizes the [Postcodes.io](https://postcodes.io/) API, an open-source project that provides UK postcode data and geolocation services.\n- Special thanks to the Postcodes.io team for their comprehensive API and open data initiatives.\n\n## Additional Notes\n\n- **Rate Limiting**: Postcodes.io does not enforce rate limiting, but it's good practice to implement it on your side if you're making a large number of requests.\n- **Data Accuracy**: While the data is regularly updated, always cross-reference critical data with official sources.\n- **API Changes**: The library is designed to handle the current API endpoints. Keep an eye on the [Postcodes.io documentation](https://postcodes.io/docs) for any changes.\n\n---\n\nFor any issues or questions, please open an issue on the GitHub repository.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python client for the Postcodes.io API used for UK postcodes",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/ymrohit/ukpostcodeio"
},
"split_keywords": [
"postcode",
" uk",
" postcodes.io",
" api",
" client"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e0fa701ab7bea7972d46ddbe03a1c595a47a1ae033a7c7fbf9c90bc2b03bce44",
"md5": "fcac1c5b75b0415718cb321748a252dc",
"sha256": "595ed39c877f0ca318346cc372238e4f5e072a4f76d731f5b3b9ff628d6d9f83"
},
"downloads": -1,
"filename": "ukpostcodeio-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fcac1c5b75b0415718cb321748a252dc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 7591,
"upload_time": "2024-10-02T00:20:45",
"upload_time_iso_8601": "2024-10-02T00:20:45.633040Z",
"url": "https://files.pythonhosted.org/packages/e0/fa/701ab7bea7972d46ddbe03a1c595a47a1ae033a7c7fbf9c90bc2b03bce44/ukpostcodeio-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "82d842abd93bc344884ba51b3dbff0e4d561747722599aa1539091a0a40d1a22",
"md5": "2f359d92f0dc120e29d5d21f1e1bf3c5",
"sha256": "57b37dcf4d4ada2087045a8751fd8a9daeb763f46d3a9a5d0dd46200a8bf8fce"
},
"downloads": -1,
"filename": "ukpostcodeio-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "2f359d92f0dc120e29d5d21f1e1bf3c5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 10243,
"upload_time": "2024-10-02T00:20:46",
"upload_time_iso_8601": "2024-10-02T00:20:46.795746Z",
"url": "https://files.pythonhosted.org/packages/82/d8/42abd93bc344884ba51b3dbff0e4d561747722599aa1539091a0a40d1a22/ukpostcodeio-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-02 00:20:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ymrohit",
"github_project": "ukpostcodeio",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ukpostcodeio"
}
JSON
