BPost Microservice

Flask based microservice to quickly validate Belgian addresses. An easy request send to this webservice, is converted and forwarded to the official bpost.be API and met with a simplified response.

As the official bpost webservice doesn't allow cross-origin resource sharing (CORS) it isn't possible to directly integrate the offical webservice with web-applications. This microservice was designed as a workaround for this limitation to validate addresses of new participants during the registration procedure for the Flemish Gut Flora Project.

In a nutshell

A simple POST request, structured as indicated below, needs to be submitted to the /validate endpoint. This address will be forwarded to the bpost validation server and the response parsed.

The response, a dictionary, will contain a "status" key, which can be "validated" or "error". In case the status is "validated" the request was successfully forwarded to the BPost API and a response obtained, if this is "error" no validation was done due to an error.

In the "fields", for each part of the address there is a key "valid" set to True or False, if the field is considered valid or not and a "suggestion", which the BPost API thinks is the correct value.

The "result" can be "valid", in which case the provided address exists and is formatted correct. If this is "warning" there are one or more mistakes found, but they can likely be corrected. If this is "error" the input does't appear to be a valid Belgian address. How many errors and warnings where thrown is stored in the "counts" field.

Finally, in "formatted" the provided and validated addresses are stored, formatted by the BPost API (e.g. for printing on labels). This are in the "submitted" and "validated" fields respectively.

Installation and testing

Using the commands below you can clone the code to your computer, set up virtualenv and install all packages. Note, if you use the included Dockerfile, you can directly install the requirements using pip.

git clone https://github.com/raeslab/bpost-ms
cd bpost-ms
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Configuration

Before running the application, you need to configure your BPost API key:

1. Obtain a BPost API key: Request API access by emailing addressvalidation@bpost.be

2. Create a .env file: Copy the example environment file:

   cp .env.example .env

3. Set your API key: Edit the .env file and replace your_api_key_here with your actual BPost API key:

   BPOST_API_KEY=your_actual_api_key_from_bpost
   

Important: Never commit your .env file to version control. It's already included in .gitignore to prevent accidental commits.

Running the Application

After all packages are installed and the configuration is complete, you can run the app using flask or using app.py

flask run

python app.py

Once the app is running got to http://127.0.0.1:5000/ to check the included demo.

Integration in your website

This webservice comes with a demo site where jQuery is used to read a form, validate the input and respond in different ways. More details how to use jQuery to integrate this service with other projects can be found here.

Examples

There are a few different scenarios (valid, warning, error) that can occur, examples of each case can be found here. Below there is an example with a valid address as input provided.

Example with valid input

Example payload to submit

{
	"Title": "Mr",
	"FirstName": "John",
	"LastName": "Doe",
	"StreetName": "Wetstraat",
	"StreetNumber": "16",
	"BoxNumber": "",
	"PostalCode": "1000",
	"MunicipalityName": "Brussel",
	"CountryName": "Belgie"
}

The response will contain for each field a key if it is valid or not and a suggestion.

Example output

{
	"status": "validated",
	"fields": {
		"Title": {
			"valid": true,
			"suggestion": "Mr"
		},
		"FirstName": {
			"valid": true,
			"suggestion": "John"
		},
		"LastName": {
			"valid": true,
			"suggestion": "Doe"
		},
		"StreetName": {
			"valid": true,
			"suggestion": "Wetstraat"
		},
		"StreetNumber": {
			"valid": true,
			"suggestion": "16"
		},
		"BoxNumber": {
			"valid": true,
			"suggestion": ""
		},
		"PostalCode": {
			"valid": true,
			"suggestion": "1000"
		},
		"MunicipalityName": {
			"valid": true,
			"suggestion": "Brussel"
		},
		"CountryName": {
			"valid": true,
			"suggestion": "Belgie"
		}
	},
	"formatted": {
		"submitted": [
			"Mr John Doe",
			"Wetstraat 16",
			"1000 Brussel"
		],
		"validated": [
			"Mr John Doe",
			"WETSTRAAT 16",
			"1000 BRUSSEL"
		]
	},
	"result": "valid",
	"counts": {
		"errors": 0,
		"warnings": 0
	},
	"GeographicalLocation": {
		"Latitude": {
			"Value": "50.9009339173",
			"CoordinateType": "DEGDEC"
		},
		"Longitude": {
			"Value": "4.6706534454",
			"CoordinateType": "DEGDEC"
		}
	}
}

Data Source

This webservice handles zip codes of municipalities a little different than the official one. The list of zip codes is available here on the BPost. Requests send to this service are formatted correctly and passed through to the BPost address validation service.