Skip to content

Commit 6b4667a

Browse files
JerrySmidtJerrySmidt
committed
Initial commit
0 parents  commit 6b4667a

File tree

14 files changed

+2640
-0
lines changed

14 files changed

+2640
-0
lines changed

‎.editorconfig‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
root = true
2+
3+
[*]
4+
indent_style = tab
5+
charset = utf-8
6+
end_of_line = lf
7+
insert_final_newline = true
8+
9+
[*.py]
10+
indent_style = space
11+
indent_size = 4

‎.gitignore‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Python-generated files
2+
__pycache__/
3+
*.py[oc]
4+
build/
5+
dist/
6+
wheels/
7+
*.egg-info
8+
9+
# Virtual environments
10+
.venv
11+
12+
# Other
13+
.gradio/

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Copyright (c) 2020, Postcode.nl B.V.
2+
All rights reserved.
3+
4+
Redistribution and use in source and binary forms, with or without modification, are
5+
permitted provided that the following conditions are met:
6+
7+
1. Redistributions of source code must retain the above copyright notice, this list of
8+
conditions and the following disclaimer.
9+
10+
2. Redistributions in binary form must reproduce the above copyright notice, this list
11+
of conditions and the following disclaimer in the documentation and/or other materials
12+
provided with the distribution.
13+
14+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
15+
OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
16+
AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
17+
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
19+
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
20+
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
21+
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

‎README.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Postcode.eu API Python Client
2+
3+
A Python client library for the [Postcode.eu API](https://developer.postcode.eu/documentation), providing access to international address autocomplete, Dutch address lookup, and validation services.
4+
5+
## Installation
6+
7+
```bash
8+
uv add postcode-eu-api-client
9+
# Or
10+
pip install postcode-eu-api-client
11+
```
12+
13+
14+
## Quick Start
15+
16+
```python
17+
from postcode_eu_api_client import Client
18+
19+
# Initialize the client
20+
client = Client('your_api_key', 'your_api_secret', 'YourApp/1.0')
21+
22+
# International address autocomplete
23+
import secrets
24+
session_id = secrets.token_hex(16)
25+
result = client.international_autocomplete(
26+
context='nld',
27+
term='den',
28+
session=session_id
29+
)
30+
31+
# Dutch postcode lookup
32+
address = client.dutch_address_by_postcode('1012JS', 1)
33+
34+
# Validate international address
35+
validation = client.validate(
36+
country='bel',
37+
postcode='2000',
38+
locality='antwerpen',
39+
street='leystraat'
40+
)
41+
```
42+
43+
## API Methods Overview
44+
45+
### International Addresses
46+
- `international_autocomplete()` - Autocomplete an address
47+
- `international_get_details()` - Get address details
48+
- `international_get_supported_countries()` - List supported countries
49+
50+
### Dutch Address Addresses
51+
- `dutch_address_by_postcode()` - Lookup by postcode and house number
52+
- `dutch_address_rd()` - Lookup by RD (Rijksdriehoeksmeting) coordinates
53+
- `dutch_address_lat_lon()` - Lookup by latitude and longitude
54+
- `dutch_address_bag_number_designation()` - Lookup by BAG Number Designation ID
55+
- `dutch_address_bag_addressable_object()` - Lookup by BAG Addressable Object ID
56+
- `dutch_address_postcode_ranges()` - Lookup streets and house number ranges by postcode
57+
58+
### Validate Addresses
59+
- `validate()` - Validate international addresses
60+
- `get_country()` - Get country information
61+
62+
### Accounts
63+
- `account_info()` - Get account information
64+
- `create_client_account()` - Create client account (resellers only)
65+
66+
View full documentation at https://developer.postcode.eu/documentation.
67+
68+
## Exception Handling
69+
70+
The client provides specific exceptions for different error conditions:
71+
72+
```python
73+
from postcode_eu_api_client import Client, InvalidPostcodeException, AuthenticationException
74+
75+
client = Client('key', 'secret', 'platform')
76+
77+
try:
78+
result = client.dutch_address_by_postcode('invalid', 1)
79+
except InvalidPostcodeException as e:
80+
print(f"Invalid postcode format: {e}")
81+
except AuthenticationException as e:
82+
print(f"Authentication failed: {e}")
83+
```
84+
85+
### Available Exceptions
86+
87+
* `PostcodeEuException` - Base exception for all Postcode.eu API client exceptions
88+
* `AuthenticationException` - Authentication failed with the API
89+
* `BadRequestException` - Bad request sent to the API
90+
* `CurlException` - HTTP request error (equivalent to cURL error in PHP)
91+
* `CurlNotLoadedException` - HTTP library not available (equivalent to cURL not loaded in PHP)
92+
* `ForbiddenException` - Access forbidden by the API
93+
* `InvalidJsonResponseException` - Invalid JSON response received from the API
94+
* `InvalidPostcodeException` - Invalid postcode format provided
95+
* `InvalidSessionValueException` - Invalid session value provided
96+
* `NotFoundException` - Resource not found
97+
* `ServerUnavailableException` - API server is unavailable
98+
* `TooManyRequestsException` - Too many requests sent to the API
99+
* `UnexpectedException` - Unexpected response from the API
100+
101+
## Requirements
102+
103+
- Python 3.10+
104+
- A postcode.eu account. Register your account at account.postcode.eu. You can test our service for free.
105+
106+
## License
107+
108+
The code is available under the Simplified BSD License, see the included LICENSE file.

‎examples/.env.example‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Postcode.eu API key (required)
2+
POSTCODE_EU_API_KEY=your-api-key
3+
4+
# Postcode.eu API secret (required)
5+
POSTCODE_EU_API_SECRET=your-api-secret

‎examples/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.env
2+
supported_countries_cache.json

‎examples/README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Postcode.eu API Methods Explorer
2+
3+
This is a Gradio-based user interface for trying out the Postcode.eu API client.
4+
5+
## Prerequisites
6+
- Make sure you have a `.env` file in this directory with your API credentials, see `.env.example`.
7+
8+
## Installation
9+
From the parent directory, install the example dependencies using [`uv`](https://github.com/astral-sh/uv):
10+
11+
```bash
12+
uv pip install -e .[examples]
13+
# or
14+
uv sync --extra examples
15+
```
16+
17+
Alternatively, you can use pip:
18+
```bash
19+
pip install -e .[examples]
20+
```
21+
22+
## Usage
23+
From the parent directory, run the script: `python -m examples.main`. This will launch a web interface where you can try out various API methods.

0 commit comments

Comments
 (0)