Skip to main content

Postal Code API

The Postal Code API can be used for:

  • postal code validation
  • getting postal code suggestions from prefix based searches
  • fetching postal code details, including city, municipality and county details
  • fetching a list of all valid postal codes for supported countries

For Norwegian, Danish and Finnish postal codes, it’s also possible to get the postal code type, e.g. normal or post office box.

Authentication

To integrate with the Bring APIs, you will need a Mybring user account with an API key. Information about prerequisites and authentication headers can be found on the general API Getting Started page.

Rate limiting

Clients exceeding 300 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.

When response bodies exceed 4kb, response is gzip compressed.

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) the API will not provide any value. For such cases it is recommended to prompt the user to input the city name themselves.

Endpoints

Base URL 
https://api.bring.com/address
Usage Method Endpoint
Get postal codes matching query GET /api/{country-code}/postal-codes
Get postal code suggestions GET /api/{country-code}/postal-codes/suggestions
Get postal code GET /api/{country-code}/postal-codes/{postal-code}
Get mailbox delivery dates at postal code GET /api/{country-code}/postal-codes/{postal-code}/mailbox-delivery-dates

OpenAPI document

https://api.bring.com/address/api-docs/postalcode

Get postal codes matching query

get 
                  https://api.bring.com/address/api/{country-code}/postal-codes

Fetches all postal codes matching provided filters.

NOTE: If no query params are provided, all postal codes of the requested country will be retrieved. When all postal codes are fetched, the page and limit params are ignored. When fetching all postal codes, only the following countries are supported: NO, DK, FI, SJ.

Request

header parameters

X-Mybring-API-Uid
Required
Description
Mybring login ID
Type
string
X-Mybring-API-Key
Required
Description
Your user's API key
Type
string
Accept
Description
Desired output media type
Type
string
Enum
application/json
application/xml
Default
application/json

path parameters

country-code
Required
Description
Country code
Type
string
Value
no

query parameters

postal_code
Description
Postal code
Type
string
Example
postal_code=1555
city
Description
City
Type
string
Example
city=Son
county
Description
County name
Type
string
Example
county=Viken
municipality
Description
Municipality name
Type
string
Example
municipality=Vestby
po_box_only
Description
Post office box postal codes only
Type
string
Enum
true
false
page
Description
Page number for paginated results
Type
integer
limit
Description
Number of results per page
Type
integer
request
Required
Type
any

Responses

200 OK

Schema

object
first
First page
string
last
Last page
string
next
Next page
string
prev
Previous page
string
self
Link to self
string
total_hits
Total number of hits
integer <int32>
Required
array of objects
city
City
string
county
County postal code is located in
string
latitude
WGS84 Latitude
string
longitude
WGS84 Longitude
string
municipality
Municipality postal code is located in
string
municipalityId
Municipality id in which postal code is located
string
po_box
Postal code is post office box
boolean
postal_code
Postal code
string
postal_code_variations
Variations of this postal code used with this city. This is only used for Dutch postal codes.
array of strings
Variations of this postal code used with this city. This is only used for Dutch postal codes.
string
special
Customer specific postal code. Only relevant for Norwegian postal codes.
boolean
object
object
first
First page
string attribute
last
Last page
string attribute
next
Next page
string attribute
prev
Previous page
string attribute
self
Link to self
string attribute
totalHits
Total number of hits
integer <int32> attribute
Required
array wrapped
object
City
Required
City
string
County
County postal code is located in
string
Latitude
WGS84 Latitude
string
Longitude
WGS84 Longitude
string
Municipality
Municipality postal code is located in
string
MunicipalityId
Municipality id in which postal code is located
string
PostOfficeBox
Postal code is post office box
boolean
Code
Required
Postal code
string
Variations of this postal code used with this city. This is only used for Dutch postal codes.
array wrapped
Code
Variations of this postal code used with this city. This is only used for Dutch postal codes.
string
Special
Customer specific postal code. Only relevant for Norwegian postal codes.
boolean
400 Bad Request

Schema

array of strings
string
Enum
INVALID_LIMIT
INVALID_PAGE_NUMBER
INVALID_POSTAL_CODE_COUNTRY
INVALID_POSTAL_CODE_FORMAT_FOR_COUNTRY
INVALID_QUERY_PARAM
array
string
Enum
INVALID_LIMIT
INVALID_PAGE_NUMBER
INVALID_POSTAL_CODE_COUNTRY
INVALID_POSTAL_CODE_FORMAT_FOR_COUNTRY
INVALID_QUERY_PARAM
429 Too Many Requests

Schema

code
string
Enum
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
description
string
object
Code
string
Enum
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
Description
string
500 Internal Server Error

Schema

code
string
Enum
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
description
string
object
Code
string
Enum
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
Description
string

Response examples

{
  "navigation": {
    "self": "https://api.bring.com/address/api/no/postal-codes?city=son&page=1",
    "total_hits": 2
  },
  "postal_codes": [
    {
      "city": "Son",
      "county": "Viken",
      "latitude": "59.5237",
      "longitude": "10.6862",
      "municipality": "Vestby",
      "municipalityId": "3019",
      "po_box": false,
      "postal_code": "1555"
    },
    {
      "city": "Son",
      "county": "Viken",
      "latitude": "59.5237",
      "longitude": "10.6862",
      "municipality": "Vestby",
      "municipalityId": "3019",
      "po_box": true,
      "postal_code": "1556"
    }
  ]
}

Get postal code suggestions

get 
                  https://api.bring.com/address/api/{country-code}/postal-codes/suggestions

Returns a list of postal codes matching provided search string.

Request

header parameters

X-Mybring-API-Uid
Required
Description
Mybring login ID
Type
string
X-Mybring-API-Key
Required
Description
Your user's API key
Type
string
Accept
Description
Desired output media type
Type
string
Enum
application/json
application/xml
Default
application/json

path parameters

country-code
Required
Description
Country code
Type
string
Value
no

query parameters

q
Required
Description
Postal code or name to filter for
Type
string
page
Description
Page number for paginated results
Type
integer
limit
Description
Number of results per page. Default 5. Max 10.
Type
integer
request
Required
Type
any

Responses

200 OK

Schema

object
first
First page
string
last
Last page
string
next
Next page
string
prev
Previous page
string
self
Link to self
string
total_hits
Total number of hits
integer <int32>
Required
array of objects
city
City
string
county
County postal code is located in
string
latitude
WGS84 Latitude
string
longitude
WGS84 Longitude
string
municipality
Municipality postal code is located in
string
municipalityId
Municipality id in which postal code is located
string
po_box
Postal code is post office box
boolean
postal_code
Postal code
string
postal_code_variations
Variations of this postal code used with this city. This is only used for Dutch postal codes.
array of strings
Variations of this postal code used with this city. This is only used for Dutch postal codes.
string
special
Customer specific postal code. Only relevant for Norwegian postal codes.
boolean
object
object
first
First page
string attribute
last
Last page
string attribute
next
Next page
string attribute
prev
Previous page
string attribute
self
Link to self
string attribute
totalHits
Total number of hits
integer <int32> attribute
Required
array wrapped
object
City
Required
City
string
County
County postal code is located in
string
Latitude
WGS84 Latitude
string
Longitude
WGS84 Longitude
string
Municipality
Municipality postal code is located in
string
MunicipalityId
Municipality id in which postal code is located
string
PostOfficeBox
Postal code is post office box
boolean
Code
Required
Postal code
string
Variations of this postal code used with this city. This is only used for Dutch postal codes.
array wrapped
Code
Variations of this postal code used with this city. This is only used for Dutch postal codes.
string
Special
Customer specific postal code. Only relevant for Norwegian postal codes.
boolean
400 Bad Request

Schema

array of strings
string
Enum
INVALID_LIMIT
INVALID_PAGE_NUMBER
INVALID_POSTAL_CODE_COUNTRY
INVALID_QUERY_PARAM
QUERY_PARAM_MISSING_OR_EMPTY
array
string
Enum
INVALID_LIMIT
INVALID_PAGE_NUMBER
INVALID_POSTAL_CODE_COUNTRY
INVALID_QUERY_PARAM
QUERY_PARAM_MISSING_OR_EMPTY
429 Too Many Requests

Schema

code
string
Enum
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
description
string
object
Code
string
Enum
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
Description
string
500 Internal Server Error

Schema

code
string
Enum
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
description
string
object
Code
string
Enum
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
Description
string

Response examples

{
  "navigation": {
    "self": "https://api.bring.com/address/api/no/postal-codes/suggestions?q=son&page=1",
    "total_hits": 2
  },
  "postal_codes": [
    {
      "city": "Son",
      "county": "Viken",
      "latitude": "59.5237",
      "longitude": "10.6862",
      "municipality": "Vestby",
      "municipalityId": "3019",
      "po_box": false,
      "postal_code": "1555"
    },
    {
      "city": "Son",
      "county": "Viken",
      "latitude": "59.5237",
      "longitude": "10.6862",
      "municipality": "Vestby",
      "municipalityId": "3019",
      "po_box": true,
      "postal_code": "1556"
    }
  ]
}

Get postal code

get 
                  https://api.bring.com/address/api/{country-code}/postal-codes/{postal-code}

Fetches details for provided postal code. A postal code may map to several cities.

NOTE: For Dutch postal codes, the provided postal code is matched against both base postal code and postal code variations, e.g. both 6101 and 6101AA will match.

Request

header parameters

X-Mybring-API-Uid
Required
Description
Mybring login ID
Type
string
X-Mybring-API-Key
Required
Description
Your user's API key
Type
string
Accept
Description
Desired output media type
Type
string
Enum
application/json
application/xml
Default
application/json

path parameters

country-code
Required
Description
Country code
Type
string
Value
no
postal-code
Required
Description
Postal code to fetch
Type
string
Example
1555

query parameters

request
Required
Type
any

Responses

200 OK

Schema

Required
array of objects
city
City
string
county
County postal code is located in
string
latitude
WGS84 Latitude
string
longitude
WGS84 Longitude
string
municipality
Municipality postal code is located in
string
municipalityId
Municipality id in which postal code is located
string
po_box
Postal code is post office box
boolean
postal_code
Postal code
string
postal_code_variations
Variations of this postal code used with this city. This is only used for Dutch postal codes.
array of strings
Variations of this postal code used with this city. This is only used for Dutch postal codes.
string
special
Customer specific postal code. Only relevant for Norwegian postal codes.
boolean
object
Required
array
object
City
Required
City
string
County
County postal code is located in
string
Latitude
WGS84 Latitude
string
Longitude
WGS84 Longitude
string
Municipality
Municipality postal code is located in
string
MunicipalityId
Municipality id in which postal code is located
string
PostOfficeBox
Postal code is post office box
boolean
Code
Required
Postal code
string
Variations of this postal code used with this city. This is only used for Dutch postal codes.
array wrapped
Code
Variations of this postal code used with this city. This is only used for Dutch postal codes.
string
Special
Customer specific postal code. Only relevant for Norwegian postal codes.
boolean
400 Bad Request

Schema

array of strings
string
Enum
INVALID_POSTAL_CODE_COUNTRY
INVALID_POSTAL_CODE_FORMAT_FOR_COUNTRY
array
string
Enum
INVALID_POSTAL_CODE_COUNTRY
INVALID_POSTAL_CODE_FORMAT_FOR_COUNTRY
429 Too Many Requests

Schema

code
string
Enum
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
description
string
object
Code
string
Enum
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
Description
string
500 Internal Server Error

Schema

code
string
Enum
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
description
string
object
Code
string
Enum
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
Description
string

Response examples

{
  "postal_codes": [
    {
      "city": "Echt",
      "county": "Limburg",
      "municipality": "Echt-Susteren",
      "po_box": false,
      "postal_code": "6101",
      "postal_code_variations": [
        "6101AA",
        "6101AB",
        "6101AC",
        "6101AD",
        "6101AE",
        "6101AG",
        "6101AH",
        "6101AJ"
      ]
    }
  ]
}

Get mailbox delivery dates at postal code

get 
                  https://api.bring.com/address/api/{country-code}/postal-codes/{postal-code}/mailbox-delivery-dates

Returns a list of coming dates when the mailman will visit the provided postal codes. Supports Norwegian postal codes only.

Request

header parameters

X-Mybring-API-Uid
Required
Description
Mybring login ID
Type
string
X-Mybring-API-Key
Required
Description
Your user's API key
Type
string
Accept
Description
Desired output media type
Type
string
Enum
application/json
application/xml
Default
application/json

path parameters

country-code
Required
Description
Country code
Type
string
Value
no
postal-code
Required
Description
Postal code to get delivery dates for
Type
string

query parameters

from_date
Description
Date from
Type
string
look_ahead_days
Description
Number of days into the future to get delivery schedule for. Default 14. Max 14.
Type
integer
request
Required
Type
any

Responses

200 OK

Schema

delivery_dates
Required
List of coming mailbox delivery dates calculated from provided date
array of strings
List of coming mailbox delivery dates calculated from provided date
string
object
Required
List of coming mailbox delivery dates calculated from provided date
array
DeliveryDate
List of coming mailbox delivery dates calculated from provided date
string
400 Bad Request

Schema

array of strings
string
Enum
INVALID_POSTAL_CODE
INVALID_QUERY_PARAM
INVALID_MAILBOX_DELIVERY_COUNTRY
INVALID_LOOK_AHEAD_DAYS
INVALID_DATE_FORMAT
array
string
Enum
INVALID_POSTAL_CODE
INVALID_QUERY_PARAM
INVALID_MAILBOX_DELIVERY_COUNTRY
INVALID_LOOK_AHEAD_DAYS
INVALID_DATE_FORMAT
429 Too Many Requests

Schema

code
string
Enum
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
description
string
object
Code
string
Enum
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
Description
string
500 Internal Server Error

Schema

code
string
Enum
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
description
string
object
Code
string
Enum
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
Description
string

Response examples

{
  "delivery_dates": [
    "2023-02-06",
    "2023-02-08",
    "2023-02-10",
    "2023-02-14",
    "2023-02-16",
    "2023-02-20"
  ]
}
comments powered by Disqus