Postal Code API – Bring Developer

Integration with shipping guide for postal code lookup is 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).

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)
list all valid postal codes for supported countries (Norway, Sweden, Denmark and Finland)

The API has two interfaces: XML and JSON.

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

There is a rate limit defined that will start throttling requests generated by your client to this API if the number of requests per second exceeds 60. When rate limiting occurs, the response will contain Http status code 429. If you have a use case requiring rates exceeding the limit, please contact developer-booking@bring.com for assistance.

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
IS - Iceland

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.
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.

Overview of endpoints

Base URL

https://api.bring.com/pickuppoint/api

Method	Endpoint	Usage
GET	/postalCode/{countryCode}/getCityAndType/{postalCode}{mediaTypeExtension}	Lookup Postal Code
GET	/postalCode/{countryCode}/getCitiesAndTypes/{postalCode}{mediaTypeExtension}	Lookup Postal Code having Multiple Cities
GET	/postalCode/{countryCode}/getAllValidPostalCodes{mediaTypeExtension}	Lookup all postal codes for Norway, Sweden, Denmark or Finland
GET	/postalCode/{countryCode}/allValidPostalCodesDetails{mediaTypeExtension}	Lookup all postal codes with details for Norway, Sweden, Denmark or Finland

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

Example: Successful

{
  "postalCode": {
    "city": "SANDVIKA",
    "postalcode": "1337",
    "postalCodeType": "NORMAL"
  }
}

Media type: application/xml

Example: Successful

<?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

Example: Successful

{
  "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

Example: Successful

<?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 or Finland

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

Example: Successful

{
  "postalCode": [
    "0001",
    "0010",
    "0015",
    "0030",
    "3000"
  ]
}

Media type: application/xml

Example: Successful

<?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 or Finland

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

Example: Successful

{
  "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

Example: Successful

<?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>

comments powered by Disqus