Postal Code API
The Postal Code API can be used to validate postal codes, and to look up the city of a given postal code for a number of countries. The API can also provide a list of all valid postal codes for Norway, Sweden, Denmark and Finland. For Norwegian postal codes, it’s also possible to retrieve the postal code type, e.g. normal or post box.
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.
Rate limiting
Clients exceeding 60 requests per second will be throttled, and the response will contain http status code 429. If you have a use case requiring rates above the limit, please contact developer-booking@bring.com for assistance.
Formats
REST XML/JSON over HTTP.
Supported Countries
- NO - Norway
- DK - Denmark
- SE - Sweden
- FI - Finland
- NL - Netherlands
- DE - Germany
- US - United States
- BE - Belgium
- FO - Faroe Islands
- GL - Greenland
- IS - Iceland
- SJ - Svalbard and Jan Mayen
The service uses GeoNames as source for most countries except Norway, Sweden, Finland.
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 (including Svalbard and Jan Mayen)
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. |
PO_BOX | Postal code contains only P.O. Box addresses. Only certain Bring services can be delivered to these addresses (see the Shipping Guide). |
SPECIAL_CUSTOMER | Special, e.g special return postal codes for selected customers. |
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.
Endpoints
Base URL
https://api.bring.com/pickuppoint/api
Usage | Method | Endpoint |
---|---|---|
Lookup Postal Code | GET |
/postalCode/{countryCode}/getCityAndType/{postalCode}{mediaTypeExtension}
|
Lookup Postal Code having Multiple Cities | GET |
/postalCode/{countryCode}/getCitiesAndTypes/{postalCode}{mediaTypeExtension}
|
Lookup all postal codes for Norway, Sweden, Denmark, Finland or Svalbard and Jan Mayen | GET |
/postalCode/{countryCode}/getAllValidPostalCodes{mediaTypeExtension}
|
Lookup all postal codes with details for Norway, Sweden, Denmark, Finland or Svalbard and Jan Mayen | GET |
/postalCode/{countryCode}/allValidPostalCodesDetails{mediaTypeExtension}
|
Lookup Postal Code
URL
GET https://api.bring.com/pickuppoint/api/postalCode/{countryCode}/getCityAndType/{postalCode}.json
https://api.bring.com/pickuppoint/api/postalCode/{countryCode}/getCityAndType/{postalCode}.xml
Request parameters
URI param | Type | Description |
---|---|---|
countryCode |
string |
Required
Country. Default value: NO Example: SE |
postalCode |
string |
Required
Postal code. Example: 1337 |
Responses
HTTP status code 200
Media type: application/json
{
"postalCode": {
"city": "SANDVIKA",
"postalcode": "1337",
"postalCodeType": "NORMAL"
}
}
Media type: application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<postalCode>
<postalCode>
<city>SANDVIKA</city>
<postalcode>1337</postalcode>
<postalCodeType>NORMAL</postalCodeType>
</postalCode>
</postalCode>
Lookup Postal Code having Multiple Cities
URL
GET https://api.bring.com/pickuppoint/api/postalCode/{countryCode}/getCitiesAndTypes/{postalCode}.json
https://api.bring.com/pickuppoint/api/postalCode/{countryCode}/getCitiesAndTypes/{postalCode}.xml
Request parameters
URI param | Type | Description |
---|---|---|
countryCode |
string |
Required
Country. Default value: NO Example: DE |
postalCode |
string |
Required
Postal code. Example: 01156 |
Responses
HTTP status code 200
Media type: application/json
{
"postalCode": [
{
"city": "Dresden",
"postalcode": "01156",
"postalCodeType": "UNKNOWN"
},
{
"city": "Dresden Gompitz, Ockerwitz",
"postalcode": "01156",
"postalCodeType": "UNKNOWN"
},
{
"city": "Dresden Gompitz",
"postalcode": "01156",
"postalCodeType": "UNKNOWN"
},
{
"city": "Dresden Altfranken",
"postalcode": "01156",
"postalCodeType": "UNKNOWN"
},
{
"city": "Dresden Gompitz, Gompitz",
"postalcode": "01156",
"postalCodeType": "UNKNOWN"
},
{
"city": "Dresden Gompitz, Unkersdorf",
"postalcode": "01156",
"postalCodeType": "UNKNOWN"
},
{
"city": "Dresden Gompitz, Pennrich",
"postalcode": "01156",
"postalCodeType": "UNKNOWN"
},
{
"city": "Dresden Gompitz, Roitzsch",
"postalcode": "01156",
"postalCodeType": "UNKNOWN"
},
{
"city": "Dresden Gompitz, Zöllmen",
"postalcode": "01156",
"postalCodeType": "UNKNOWN"
},
{
"city": "Dresden Gompitz, Steinbach",
"postalcode": "01156",
"postalCodeType": "UNKNOWN"
}
]
}
Media type: application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<postalCodes>
<postalCode>
<city>Dresden</city>
<postalcode>01156</postalcode>
<postalCodeType>UNKNOWN</postalCodeType>
</postalCode>
<postalCode>
<city>Dresden Gompitz, Ockerwitz</city>
<postalcode>01156</postalcode>
<postalCodeType>UNKNOWN</postalCodeType>
</postalCode>
<postalCode>
<city>Dresden Gompitz</city>
<postalcode>01156</postalcode>
<postalCodeType>UNKNOWN</postalCodeType>
</postalCode>
<postalCode>
<city>Dresden Altfranken</city>
<postalcode>01156</postalcode>
<postalCodeType>UNKNOWN</postalCodeType>
</postalCode>
<postalCode>
<city>Dresden Gompitz, Gompitz</city>
<postalcode>01156</postalcode>
<postalCodeType>UNKNOWN</postalCodeType>
</postalCode>
<postalCode>
<city>Dresden Gompitz, Unkersdorf</city>
<postalcode>01156</postalcode>
<postalCodeType>UNKNOWN</postalCodeType>
</postalCode>
<postalCode>
<city>Dresden Gompitz, Pennrich</city>
<postalcode>01156</postalcode>
<postalCodeType>UNKNOWN</postalCodeType>
</postalCode>
<postalCode>
<city>Dresden Gompitz, Roitzsch</city>
<postalcode>01156</postalcode>
<postalCodeType>UNKNOWN</postalCodeType>
</postalCode>
<postalCode>
<city>Dresden Gompitz, Zöllmen</city>
<postalcode>01156</postalcode>
<postalCodeType>UNKNOWN</postalCodeType>
</postalCode>
<postalCode>
<city>Dresden Gompitz, Steinbach</city>
<postalcode>01156</postalcode>
<postalCodeType>UNKNOWN</postalCodeType>
</postalCode>
</postalCodes>
Lookup all postal codes for Norway, Sweden, Denmark, Finland or Svalbard and Jan Mayen
URL
GET https://api.bring.com/pickuppoint/api/postalCode/{countryCode}/getAllValidPostalCodes.json
https://api.bring.com/pickuppoint/api/postalCode/{countryCode}/getAllValidPostalCodes.xml
Request parameters
URI param | Type | Description |
---|---|---|
countryCode |
string |
Required
Country. Default value: NO Example: DE |
Responses
HTTP status code 200
Media type: application/json
{
"postalCode": [
"0001",
"0010",
"0015",
"0030",
"3000"
]
}
Media type: application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<postalCodes>
<postalCode>0001</postalCode>
<postalCode>0010</postalCode>
<postalCode>0015</postalCode>
<postalCode>0030</postalCode>
<postalCode>3000</postalCode>
</postalCodes>
Lookup all postal codes with details for Norway, Sweden, Denmark, Finland or Svalbard and Jan Mayen
URL
GET https://api.bring.com/pickuppoint/api/postalCode/{countryCode}/allValidPostalCodesDetails.json
https://api.bring.com/pickuppoint/api/postalCode/{countryCode}/allValidPostalCodesDetails.xml
Request parameters
URI param | Type | Description |
---|---|---|
countryCode |
string |
Required
Country. Default value: NO Example: DE |
Responses
HTTP status code 200
Media type: application/json
{
"postalCode": [
{
"city": "OSLO",
"postalcode": "0001",
"postalCodeType": "PO_BOX"
},
{
"city": "OSLO",
"postalcode": "0010",
"postalCodeType": "NORMAL"
},
{
"city": "OSLO",
"postalcode": "0015",
"postalCodeType": "NORMAL"
},
{
"city": "OSLO",
"postalcode": "0018",
"postalCodeType": "NORMAL"
},
{
"city": "OSLO",
"postalcode": "0021",
"postalCodeType": "PO_BOX"
},
{
"city": "OSLO",
"postalcode": "0024",
"postalCodeType": "PO_BOX"
},
{
"city": "OSLO",
"postalcode": "0026",
"postalCodeType": "NORMAL"
},
{
"city": "DRAMMEN",
"postalcode": "3000",
"postalCodeType": "SPECIAL_CUSTOMER"
}
]
}
Media type: application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<postalCodes>
<postalCode>
<city>OSLO</city>
<postalcode>0001</postalcode>
<postalCodeType>PO_BOX</postalCodeType>
</postalCode>
<postalCode>
<city>OSLO</city>
<postalcode>0010</postalcode>
<postalCodeType>NORMAL</postalCodeType>
</postalCode>
<postalCode>
<city>OSLO</city>
<postalcode>0015</postalcode>
<postalCodeType>NORMAL</postalCodeType>
</postalCode>
<postalCode>
<city>OSLO</city>
<postalcode>0018</postalcode>
<postalCodeType>NORMAL</postalCodeType>
</postalCode>
<postalCode>
<city>OSLO</city>
<postalcode>0021</postalcode>
<postalCodeType>PO_BOX</postalCodeType>
</postalCode>
<postalCode>
<city>OSLO</city>
<postalcode>0024</postalcode>
<postalCodeType>PO_BOX</postalCodeType>
</postalCode>
<postalCode>
<city>OSLO</city>
<postalcode>0026</postalcode>
<postalCodeType>NORMAL</postalCodeType>
</postalCode>
<postalCode>
<city>DRAMMEN</city>
<postalcode>3000</postalcode>
<postalCodeType>SPECIAL_CUSTOMER</postalCodeType>
</postalCode>
</postalCodes>