Postal Code API

Introduction

With the Postal Code API you can

validate a postal code
look up the city of a postal code
get the postal code type, e.g. normal or P.O. Box (for Norway)

The API has three interfaces: XML, JSON and HTML.

It is NOT possible to get data in batch or get list of valid postal codes for a given country at a regular interval.

Supported Countries

The following countries are supported:

NO - Norway
DK - Denmark
SE - Sweden
FI - Finland
NL - Netherlands
DE - Germany
US - United States
BE - Belgium
FO - Faroe Islands
GL - Greenland

The service uses GeoNames as source for all countries except Norway.

For unsupported countries (countries not in the list above), all postal codes will be marked as valid with no city name returned. In these cases it is recommended to prompt the user to input the city name themselves.

For countries that have multiple results (cities) for a given postal code, a list of cities will be returned. See example below.

Postal Code type for Norway

For Norway, you also get information about the postal code type. This is set in the postalCodeType in the response:

`postalCodeType`	Description
NORMAL	Normal postal code suitable for delivering packages. Contains street addresses or mix of street and other postal code types.
POBOX	Postal code contains only P.O. Box addresses. Only certain Bring products can be delivered to these addresses (see the Shipping Guide).
SPECIALCUSTOMER	Special, e.g special return postal codes for selected customers.
SPECIALNOSTREET	Special, e.g special postal codes for customers with old “serviceboks”.
UNKNOWN	Unknown postal code type. Used for e.g. international postal codes.

Overview of endpoints

Base URL

https://api.bring.com/shippingguide/api

Method	Endpoint	Usage
GET	/postalCode{mediaTypeExtension}	Lookup postal code

Lookup postal code

TODO: description

URL

https://api.bring.com/shippingguide/api/postalCode.json
https://api.bring.com/shippingguide/api/postalCode.xml
https://api.bring.com/shippingguide/api/postalCode.html

Request params

Query parameter	Type	Description
`clientUrl`	`string`	Required. Client URL. To use the API you must specify a client url parameter. The client url should be set to the url of the web shop or application the end user is ordering from. The client url can be sent as a url parameter, clientUrl, or as a header, `X-Bring-Client-URL`. Example: `https://www.example.com/amazing-clothes/`
`pnr`	`string`	Required. Postal code. Example: `1337`
`country`	`string`	Optional. Country. Default value: `Norway` Example: `1337`
`callback`	`string`	Optional. JSONP callback function. Example: `callback`

Response

Successful response (200)

{
  "result": "SANDVIKA",
  "valid": true,
  "postalCodeType": "NORMAL" 
}

<?xml version="1.0" encoding="UTF-8"?>
<PostalCodeQueryResponse>
  <Response valid="true" postalCodeType="NORMAL">SANDVIKA</Response>
</PostalCodeQueryResponse>

<span id="bringPostnumberQueryResult" class="bringPostnumberQueryValidPostnumber bringPostalCodeTypeNORMAL">SANDVIKA</span>

More examples

Finding the location for postal codes with multiple locations

In some countries, such as for example Germany and France, postal codes are non-unique. This means that one postal code might have multiple city names. In these cases the integration APIs (json and xml) will have separate elements containing the list of cities, while the ordinary html response element will remain blank.

Example request: …&country=DE&pnr=99869

JSON
XML

{
    "result": "",
    "valid": true,
    "postalCodeType": "UNKNOWN",
    "multipleMatches": [
        "Ballstädt", 
        "Brüheim", 
        "Bufleben", 
        "Ebenheim", 
        "Emleben", 
        "Eschenbergen", 
        "Friedrichswerth", 
        "Friemar", 
        "Goldbach", 
        "Grabsleben", 
        "Günthersleben", 
        "Haina", 
        "Hochheim", 
        "Molschleben", 
        "Mühlberg", 
        "Pferdingsleben", 
        "Remstädt", 
        "Schwabhausen", 
        "Seebergen", 
        "Sonneborn", 
        "Tröchtelborn", 
        "Tüttleben", 
        "Wandersleben", 
        "Wangenheim", 
        "Warza", 
        "Wechmar", 
        "Weingarten", 
        "Westhausen"
    ]
}

<?xml version="1.0" encoding="UTF-8"?>
<PostalCodeQueryResponse>
    <Response valid="true" postalCodeType="UNKNOWN"></Response>
    <MultipleMatches>
        <Value>Ballstädt</Value>
        <Value>Brüheim</Value>
        <Value>Bufleben</Value>
        <Value>Ebenheim</Value>
        <Value>Emleben</Value>
        <Value>Eschenbergen</Value>
        <Value>Friedrichswerth</Value>
        <Value>Friemar</Value>
        <Value>Goldbach</Value>
        <Value>Grabsleben</Value>
        <Value>Günthersleben</Value>
        <Value>Haina</Value>
        <Value>Hochheim</Value>
        <Value>Molschleben</Value>
        <Value>Mühlberg</Value>
        <Value>Pferdingsleben</Value>
        <Value>Remstädt</Value>
        <Value>Schwabhausen</Value>
        <Value>Seebergen</Value>
        <Value>Sonneborn</Value>
        <Value>Tröchtelborn</Value>
        <Value>Tüttleben</Value>
        <Value>Wandersleben</Value>
        <Value>Wangenheim</Value>
        <Value>Warza</Value>
        <Value>Wechmar</Value>
        <Value>Weingarten</Value>
        <Value>Westhausen</Value>
    </MultipleMatches>
</PostalCodeQueryResponse>