Postal Code API

Introduction

Integration with shipping guide for postal code lookup will soon be deprecated (Base url: https://api.bring.com/shippingguide/api). We recommend switching to pickup point if you have not already done so (Base url: https://api.bring.com/pickuppoint/api).

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.

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.

Steps for Authentication

Before you can begin using the postal code API you’ll have to do the following:

1. Get your API key from Mybring

To make API requests you will need an API key. Click the link below, which sends you to your “Settings and API” page in Mybring profile administration. Scroll down to the “API key” section. Your generated API key which you will use to authenticate your requests can be found here.

Get API key

2. Add authentication headers

A description of the headers can be found in Getting Started / Authentication.

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>