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 two interfaces: XML and JSON.
It is NOT possible to get data in batch or get list of valid postal codes for a given country at a regular interval.
Authentication
The Postal Code API requires authentication. To make API requests, you will need an API key from Mybring. Steps for getting a key and description of headers can be found on the general API Getting Started / Authentication page.
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 most 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 services 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. |
Support CORS
CORS headers will be added to response only for authenticated requests.
Overview of endpoints
Base URL
https://api.bring.com/pickuppoint/api
Method | Endpoint | Usage |
---|---|---|
GET | /postalCode/{countryCode}/getCityAndType/{postalCode}{mediaTypeExtension} | Lookup Postal Code |
Lookup Postal Code
URL
https://api.bring.com/pickuppoint/api/postalCode/{countryCode}/getCityAndType/{postalCode}.json
https://api.bring.com/pickuppoint/api/postalCode/{countryCode}/getCityAndType/{postalCode}.xml
Request params
URI parameter | Type | Description |
---|---|---|
countryCode |
string |
Required. Country. Default value: NO
Example: SE
|
postalCode |
string |
Required. Postal code. Example: 1337
|
Response
Successful response (200)
{
"postalCode": {
"city": "SANDVIKA",
"postalcode": "1337",
"postalCodeType": "NORMAL"
}
}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<postalCode>
<postalCode>
<city>SANDVIKA</city>
<postalcode>1337</postalcode>
<postalCodeType>NORMAL</postalCodeType>
</postalCode>
</postalCode>