International Postcode Lookup API

This is a Java Dropwizard API wrapper around DHL's publicly available Routing Reference Data. It uses a subset of the data to allow international postcode lookups. This is useful for companies that have DHL as a delivery partner and want to ensure that the postcode and city combination match the ones that DHL use.

This supports ESDv6 (latest version on 21 April 2014).

Please note that:

• this is Alpha software quality and under heavy development; and
• this is not affiliated with or endorsed by DHL; and
• this project only gives you data conversion tools and a REST wrapper around DHL's data set. You still need to agree with DHL whether you can use the data set for your intendend purposes.

Get your REST service running

1. Make sure you have mongodb installed
2. Run the MongoDB database: mongod
3. Clone this git repository: git clone [email protected]:leeprovoost/international-postcode-lookup-api.git
4. Import the DHL data, follow instructions here.
5. Go into the rest-service folder and build the service: ./build.sh
6. Start the REST service: ./run.sh

Test the REST service directly

• View API listing: http://localhost:3000/api-docs
• View Swagger UI: http://localhost:3000/swagger-ui/index.html
• Get list of all countries: http://localhost:3000/intl-postcode-api/countries/
• Get list of all country postcode formatting rules: http://localhost:3000/intl-postcode-api/country-postcodes/
• Get list of cities (by default limited to 25): http://localhost:3000/intl-postcode-api/cities/
• View postcode lookup results: http://localhost:3000/intl-postcode-api/cities/?country=GB&postcode=SW8

Use the experimental JQuery front-end

Note: there is currently a small reload bug, so when you want to enter a new country, just load the page again. Will fix it in the next release.

1. Host the HTML page on your local Apache server
2. Open http://localhost/frontend-jquery/index.html (add the right port number)
3. Start typing in a postcode or a city

TODO

See issues page