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.

Subscribe to updates

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`

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.

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

Responses

200 OK

object

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

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

array of objects

code: string

Enum
INVALID_QUERY_PARAM
INVALID_COUNTRY
INVALID_MAILBOX_DELIVERY_COUNTRY
INVALID_POSTAL_CODE_COUNTRY
QUERY_PARAM_MISSING_OR_EMPTY
QUERY_PARAM_EMPTY
INVALID_PAGE_NUMBER
INVALID_LIMIT
LIMIT_LARGER_THAN_10
LIMIT_LARGER_THAN_20
INVALID_POSTAL_CODE
INVALID_DATE_FORMAT
INVALID_LOOK_AHEAD_DAYS
INVALID_POSTAL_CODE_FORMAT_FOR_COUNTRY
INVALID_ADDRESS_STRING
ADDRESS_PARAM_PROVIDED
MISSING_ADDRESS_TYPE
INVALID_ADDRESS_TYPE
MISSING_STREET_OR_PLACE
MISSING_POSTAL_CODE_OR_CITY_POSTAL_PLACE_ADDRESS
MISSING_CITY_POSTAL_PLACE_ADDRESS
MISSING_OR_INVALID_POSTAL_CODE
INVALID_STREET_NUMBER
INVALID_PO_BOX_NUMBER
INVALID_LETTER
NO_QUERY_PARAMS
MISSING_STREET_NUMBER
MISSING_PO_BOX_NUMBER
MISSING_POSTAL_CODE
INVALID_COUNTRY_CODE
UNSUPPORTED_COUNTRY_CODE
MISSING_SEARCH_EXPRESSION
description: string

array

object

Code: string

Enum
INVALID_QUERY_PARAM
INVALID_COUNTRY
INVALID_MAILBOX_DELIVERY_COUNTRY
INVALID_POSTAL_CODE_COUNTRY
QUERY_PARAM_MISSING_OR_EMPTY
QUERY_PARAM_EMPTY
INVALID_PAGE_NUMBER
INVALID_LIMIT
LIMIT_LARGER_THAN_10
LIMIT_LARGER_THAN_20
INVALID_POSTAL_CODE
INVALID_DATE_FORMAT
INVALID_LOOK_AHEAD_DAYS
INVALID_POSTAL_CODE_FORMAT_FOR_COUNTRY
INVALID_ADDRESS_STRING
ADDRESS_PARAM_PROVIDED
MISSING_ADDRESS_TYPE
INVALID_ADDRESS_TYPE
MISSING_STREET_OR_PLACE
MISSING_POSTAL_CODE_OR_CITY_POSTAL_PLACE_ADDRESS
MISSING_CITY_POSTAL_PLACE_ADDRESS
MISSING_OR_INVALID_POSTAL_CODE
INVALID_STREET_NUMBER
INVALID_PO_BOX_NUMBER
INVALID_LETTER
NO_QUERY_PARAMS
MISSING_STREET_NUMBER
MISSING_PO_BOX_NUMBER
MISSING_POSTAL_CODE
INVALID_COUNTRY_CODE
UNSUPPORTED_COUNTRY_CODE
MISSING_SEARCH_EXPRESSION
Description: string

429 Too Many Requests

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

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"
    }
  ]
}

{
  "navigation": {
    "self": "https://api.bring.com/address/api/no/postal-codes?county=viken&municipality=vestby&page=1",
    "total_hits": 4
  },
  "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"
    },
    {
      "city": "Hølen",
      "county": "Viken",
      "latitude": "59.5237",
      "longitude": "10.6862",
      "municipality": "Vestby",
      "municipalityId": "3019",
      "po_box": false,
      "postal_code": "1540"
    },
    {
      "city": "Hvitsten",
      "county": "Viken",
      "latitude": "59.5237",
      "longitude": "10.6862",
      "municipality": "Vestby",
      "municipalityId": "3019",
      "po_box": false,
      "postal_code": "1545"
    }
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<PostalCodes>
  <Navigation self="https://api.bring.com/address/api/no/postal-codes?city=son&page=1" totalHits="2">
  </Navigation>
  <PostalCodeList>
    <PostalCode>
      <City>Son</City>
      <County>Viken</County>
      <Latitude>59.5237</Latitude>
      <Longitude>10.6862</Longitude>
      <Municipality>Vestby</Municipality>
      <MunicipalityId>3019</MunicipalityId>
      <Code>1555</Code>
    </PostalCode>
    <PostalCode>
      <City>Son</City>
      <County>Viken</County>
      <Latitude>59.5237</Latitude>
      <Longitude>10.6862</Longitude>
      <Municipality>Vestby</Municipality>
      <MunicipalityId>3019</MunicipalityId>
      <PostOfficeBox>true</PostOfficeBox>
      <Code>1556</Code>
    </PostalCode>
  </PostalCodeList>
</PostalCodes>

<?xml version="1.0" encoding="UTF-8"?>
<PostalCodes>
  <Navigation self="https://api.bring.com/address/api/no/postal-codes?county=viken&municipality=vestby&page=1" totalHits="4">
  </Navigation>
  <PostalCodeList>
    <PostalCode>
      <City>Son</City>
      <County>Viken</County>
      <Latitude>59.5237</Latitude>
      <Longitude>10.6862</Longitude>
      <Municipality>Vestby</Municipality>
      <MunicipalityId>3019</MunicipalityId>
      <Code>1555</Code>
    </PostalCode>
    <PostalCode>
      <City>Son</City>
      <County>Viken</County>
      <Latitude>59.5237</Latitude>
      <Longitude>10.6862</Longitude>
      <Municipality>Vestby</Municipality>
      <MunicipalityId>3019</MunicipalityId>
      <PostOfficeBox>true</PostOfficeBox>
      <Code>1556</Code>
    </PostalCode>
    <PostalCode>
      <City>Hølen</City>
      <County>Viken</County>
      <Latitude>59.5237</Latitude>
      <Longitude>10.6862</Longitude>
      <Municipality>Vestby</Municipality>
      <MunicipalityId>3019</MunicipalityId>
      <Code>1540</Code>
    </PostalCode>
    <PostalCode>
      <City>Hvitsten</City>
      <County>Viken</County>
      <Latitude>59.5237</Latitude>
      <Longitude>10.6862</Longitude>
      <Municipality>Vestby</Municipality>
      <MunicipalityId>3019</MunicipalityId>
      <Code>1545</Code>
    </PostalCode>
  </PostalCodeList>
</PostalCodes>

{
  "code": "INVALID_LIMIT",
  "description": "The `limit` query param must be numeric"
}

<?xml version="1.0" encoding="UTF-8"?>
<!-- Example cannot be generated; root element name is undefined -->

{
  "code": "RATE_LIMIT_EXCEEDED",
  "description": "Request rate cannot exceed 40 requests per 1 second"
}

<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>RATE_LIMIT_EXCEEDED</Code>
  <Description>Request rate cannot exceed 40 requests per 1 second</Description>
</Error>

{
  "code": "INTERNAL_ERROR",
  "description": "An unexpected error occurred"
}

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

Responses

200 OK

object

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

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

array of objects

code: string

Enum
INVALID_QUERY_PARAM
INVALID_COUNTRY
INVALID_MAILBOX_DELIVERY_COUNTRY
INVALID_POSTAL_CODE_COUNTRY
QUERY_PARAM_MISSING_OR_EMPTY
QUERY_PARAM_EMPTY
INVALID_PAGE_NUMBER
INVALID_LIMIT
LIMIT_LARGER_THAN_10
LIMIT_LARGER_THAN_20
INVALID_POSTAL_CODE
INVALID_DATE_FORMAT
INVALID_LOOK_AHEAD_DAYS
INVALID_POSTAL_CODE_FORMAT_FOR_COUNTRY
INVALID_ADDRESS_STRING
ADDRESS_PARAM_PROVIDED
MISSING_ADDRESS_TYPE
INVALID_ADDRESS_TYPE
MISSING_STREET_OR_PLACE
MISSING_POSTAL_CODE_OR_CITY_POSTAL_PLACE_ADDRESS
MISSING_CITY_POSTAL_PLACE_ADDRESS
MISSING_OR_INVALID_POSTAL_CODE
INVALID_STREET_NUMBER
INVALID_PO_BOX_NUMBER
INVALID_LETTER
NO_QUERY_PARAMS
MISSING_STREET_NUMBER
MISSING_PO_BOX_NUMBER
MISSING_POSTAL_CODE
INVALID_COUNTRY_CODE
UNSUPPORTED_COUNTRY_CODE
MISSING_SEARCH_EXPRESSION
description: string

array

object

Code: string

Enum
INVALID_QUERY_PARAM
INVALID_COUNTRY
INVALID_MAILBOX_DELIVERY_COUNTRY
INVALID_POSTAL_CODE_COUNTRY
QUERY_PARAM_MISSING_OR_EMPTY
QUERY_PARAM_EMPTY
INVALID_PAGE_NUMBER
INVALID_LIMIT
LIMIT_LARGER_THAN_10
LIMIT_LARGER_THAN_20
INVALID_POSTAL_CODE
INVALID_DATE_FORMAT
INVALID_LOOK_AHEAD_DAYS
INVALID_POSTAL_CODE_FORMAT_FOR_COUNTRY
INVALID_ADDRESS_STRING
ADDRESS_PARAM_PROVIDED
MISSING_ADDRESS_TYPE
INVALID_ADDRESS_TYPE
MISSING_STREET_OR_PLACE
MISSING_POSTAL_CODE_OR_CITY_POSTAL_PLACE_ADDRESS
MISSING_CITY_POSTAL_PLACE_ADDRESS
MISSING_OR_INVALID_POSTAL_CODE
INVALID_STREET_NUMBER
INVALID_PO_BOX_NUMBER
INVALID_LETTER
NO_QUERY_PARAMS
MISSING_STREET_NUMBER
MISSING_PO_BOX_NUMBER
MISSING_POSTAL_CODE
INVALID_COUNTRY_CODE
UNSUPPORTED_COUNTRY_CODE
MISSING_SEARCH_EXPRESSION
Description: string

429 Too Many Requests

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

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"
    }
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<PostalCodes>
  <Navigation self="https://api.bring.com/address/api/no/postal-codes/suggestions?q=son&page=1" totalHits="2">
  </Navigation>
  <PostalCodeList>
    <PostalCode>
      <City>Son</City>
      <County>Viken</County>
      <Latitude>59.5237</Latitude>
      <Longitude>10.6862</Longitude>
      <Municipality>Vestby</Municipality>
      <MunicipalityId>3019</MunicipalityId>
      <Code>1555</Code>
    </PostalCode>
    <PostalCode>
      <City>Son</City>
      <County>Viken</County>
      <Latitude>59.5237</Latitude>
      <Longitude>10.6862</Longitude>
      <Municipality>Vestby</Municipality>
      <MunicipalityId>3019</MunicipalityId>
      <PostOfficeBox>true</PostOfficeBox>
      <Code>1556</Code>
    </PostalCode>
  </PostalCodeList>
</PostalCodes>

{
  "code": "INVALID_LIMIT",
  "description": "The `limit` query param must be numeric"
}

<?xml version="1.0" encoding="UTF-8"?>
<!-- Example cannot be generated; root element name is undefined -->

{
  "code": "RATE_LIMIT_EXCEEDED",
  "description": "Request rate cannot exceed 40 requests per 1 second"
}

<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>RATE_LIMIT_EXCEEDED</Code>
  <Description>Request rate cannot exceed 40 requests per 1 second</Description>
</Error>

{
  "code": "INTERNAL_ERROR",
  "description": "An unexpected error occurred"
}

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

Responses

200 OK

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

array of objects

code: string

Enum
INVALID_QUERY_PARAM
INVALID_COUNTRY
INVALID_MAILBOX_DELIVERY_COUNTRY
INVALID_POSTAL_CODE_COUNTRY
QUERY_PARAM_MISSING_OR_EMPTY
QUERY_PARAM_EMPTY
INVALID_PAGE_NUMBER
INVALID_LIMIT
LIMIT_LARGER_THAN_10
LIMIT_LARGER_THAN_20
INVALID_POSTAL_CODE
INVALID_DATE_FORMAT
INVALID_LOOK_AHEAD_DAYS
INVALID_POSTAL_CODE_FORMAT_FOR_COUNTRY
INVALID_ADDRESS_STRING
ADDRESS_PARAM_PROVIDED
MISSING_ADDRESS_TYPE
INVALID_ADDRESS_TYPE
MISSING_STREET_OR_PLACE
MISSING_POSTAL_CODE_OR_CITY_POSTAL_PLACE_ADDRESS
MISSING_CITY_POSTAL_PLACE_ADDRESS
MISSING_OR_INVALID_POSTAL_CODE
INVALID_STREET_NUMBER
INVALID_PO_BOX_NUMBER
INVALID_LETTER
NO_QUERY_PARAMS
MISSING_STREET_NUMBER
MISSING_PO_BOX_NUMBER
MISSING_POSTAL_CODE
INVALID_COUNTRY_CODE
UNSUPPORTED_COUNTRY_CODE
MISSING_SEARCH_EXPRESSION
description: string

array

object

Code: string

Enum
INVALID_QUERY_PARAM
INVALID_COUNTRY
INVALID_MAILBOX_DELIVERY_COUNTRY
INVALID_POSTAL_CODE_COUNTRY
QUERY_PARAM_MISSING_OR_EMPTY
QUERY_PARAM_EMPTY
INVALID_PAGE_NUMBER
INVALID_LIMIT
LIMIT_LARGER_THAN_10
LIMIT_LARGER_THAN_20
INVALID_POSTAL_CODE
INVALID_DATE_FORMAT
INVALID_LOOK_AHEAD_DAYS
INVALID_POSTAL_CODE_FORMAT_FOR_COUNTRY
INVALID_ADDRESS_STRING
ADDRESS_PARAM_PROVIDED
MISSING_ADDRESS_TYPE
INVALID_ADDRESS_TYPE
MISSING_STREET_OR_PLACE
MISSING_POSTAL_CODE_OR_CITY_POSTAL_PLACE_ADDRESS
MISSING_CITY_POSTAL_PLACE_ADDRESS
MISSING_OR_INVALID_POSTAL_CODE
INVALID_STREET_NUMBER
INVALID_PO_BOX_NUMBER
INVALID_LETTER
NO_QUERY_PARAMS
MISSING_STREET_NUMBER
MISSING_PO_BOX_NUMBER
MISSING_POSTAL_CODE
INVALID_COUNTRY_CODE
UNSUPPORTED_COUNTRY_CODE
MISSING_SEARCH_EXPRESSION
Description: string

429 Too Many Requests

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

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"
      ]
    }
  ]
}

{
  "postal_codes": [
    {
      "city": "Dresden innere altstadt",
      "county": "Sachsen",
      "latitude": "59.5237",
      "longitude": "10.6862",
      "municipalityId": "3019",
      "po_box": false,
      "postal_code": "01067"
    },
    {
      "city": "Dresden",
      "county": "Sachsen",
      "latitude": "59.5237",
      "longitude": "10.6862",
      "municipalityId": "3019",
      "po_box": false,
      "postal_code": "01067"
    },
    {
      "city": "Dresden friedrichstadt",
      "county": "Sachsen",
      "latitude": "59.5237",
      "longitude": "10.6862",
      "municipalityId": "3019",
      "po_box": false,
      "postal_code": "01067"
    }
  ]
}

{
  "postal_codes": [
    {
      "city": "Son",
      "county": "Viken",
      "latitude": "59.5237",
      "longitude": "10.6862",
      "municipality": "Vestby",
      "municipalityId": "3019",
      "po_box": false,
      "postal_code": "1555"
    }
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<PostalCodes>
  <PostalCode>
    <PostalCode>
      <City>Echt</City>
      <County>Limburg</County>
      <Municipality>Echt-Susteren</Municipality>
      <Code>6101</Code>
      <PostalCodeVariations>
        <Code>6101AA</Code>
        <Code>6101AB</Code>
        <Code>6101AC</Code>
        <Code>6101AD</Code>
        <Code>6101AE</Code>
        <Code>6101AG</Code>
        <Code>6101AH</Code>
        <Code>6101AJ</Code>
      </PostalCodeVariations>
    </PostalCode>
  </PostalCode>
</PostalCodes>

<?xml version="1.0" encoding="UTF-8"?>
<PostalCodes>
  <PostalCode>
    <PostalCode>
      <City>Dresden innere altstadt</City>
      <County>Sachsen</County>
      <Latitude>59.5237</Latitude>
      <Longitude>10.6862</Longitude>
      <MunicipalityId>3019</MunicipalityId>
      <Code>01067</Code>
    </PostalCode>
    <PostalCode>
      <City>Dresden</City>
      <County>Sachsen</County>
      <Latitude>59.5237</Latitude>
      <Longitude>10.6862</Longitude>
      <MunicipalityId>3019</MunicipalityId>
      <Code>01067</Code>
    </PostalCode>
    <PostalCode>
      <City>Dresden friedrichstadt</City>
      <County>Sachsen</County>
      <Latitude>59.5237</Latitude>
      <Longitude>10.6862</Longitude>
      <MunicipalityId>3019</MunicipalityId>
      <Code>01067</Code>
    </PostalCode>
  </PostalCode>
</PostalCodes>

<?xml version="1.0" encoding="UTF-8"?>
<PostalCodes>
  <PostalCode>
    <PostalCode>
      <City>Son</City>
      <County>Viken</County>
      <Latitude>59.5237</Latitude>
      <Longitude>10.6862</Longitude>
      <Municipality>Vestby</Municipality>
      <MunicipalityId>3019</MunicipalityId>
      <Code>1555</Code>
    </PostalCode>
  </PostalCode>
</PostalCodes>

{
  "code": "INVALID_POSTAL_CODE_COUNTRY",
  "description": "The provided country code is not supported"
}

<?xml version="1.0" encoding="UTF-8"?>
<!-- Example cannot be generated; root element name is undefined -->

{
  "code": "RATE_LIMIT_EXCEEDED",
  "description": "Request rate cannot exceed 40 requests per 1 second"
}

<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>RATE_LIMIT_EXCEEDED</Code>
  <Description>Request rate cannot exceed 40 requests per 1 second</Description>
</Error>

{
  "code": "INTERNAL_ERROR",
  "description": "An unexpected error occurred"
}

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

Responses

200 OK

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

array of objects

code: string

Enum
INVALID_QUERY_PARAM
INVALID_COUNTRY
INVALID_MAILBOX_DELIVERY_COUNTRY
INVALID_POSTAL_CODE_COUNTRY
QUERY_PARAM_MISSING_OR_EMPTY
QUERY_PARAM_EMPTY
INVALID_PAGE_NUMBER
INVALID_LIMIT
LIMIT_LARGER_THAN_10
LIMIT_LARGER_THAN_20
INVALID_POSTAL_CODE
INVALID_DATE_FORMAT
INVALID_LOOK_AHEAD_DAYS
INVALID_POSTAL_CODE_FORMAT_FOR_COUNTRY
INVALID_ADDRESS_STRING
ADDRESS_PARAM_PROVIDED
MISSING_ADDRESS_TYPE
INVALID_ADDRESS_TYPE
MISSING_STREET_OR_PLACE
MISSING_POSTAL_CODE_OR_CITY_POSTAL_PLACE_ADDRESS
MISSING_CITY_POSTAL_PLACE_ADDRESS
MISSING_OR_INVALID_POSTAL_CODE
INVALID_STREET_NUMBER
INVALID_PO_BOX_NUMBER
INVALID_LETTER
NO_QUERY_PARAMS
MISSING_STREET_NUMBER
MISSING_PO_BOX_NUMBER
MISSING_POSTAL_CODE
INVALID_COUNTRY_CODE
UNSUPPORTED_COUNTRY_CODE
MISSING_SEARCH_EXPRESSION
description: string

array

object

Code: string

Enum
INVALID_QUERY_PARAM
INVALID_COUNTRY
INVALID_MAILBOX_DELIVERY_COUNTRY
INVALID_POSTAL_CODE_COUNTRY
QUERY_PARAM_MISSING_OR_EMPTY
QUERY_PARAM_EMPTY
INVALID_PAGE_NUMBER
INVALID_LIMIT
LIMIT_LARGER_THAN_10
LIMIT_LARGER_THAN_20
INVALID_POSTAL_CODE
INVALID_DATE_FORMAT
INVALID_LOOK_AHEAD_DAYS
INVALID_POSTAL_CODE_FORMAT_FOR_COUNTRY
INVALID_ADDRESS_STRING
ADDRESS_PARAM_PROVIDED
MISSING_ADDRESS_TYPE
INVALID_ADDRESS_TYPE
MISSING_STREET_OR_PLACE
MISSING_POSTAL_CODE_OR_CITY_POSTAL_PLACE_ADDRESS
MISSING_CITY_POSTAL_PLACE_ADDRESS
MISSING_OR_INVALID_POSTAL_CODE
INVALID_STREET_NUMBER
INVALID_PO_BOX_NUMBER
INVALID_LETTER
NO_QUERY_PARAMS
MISSING_STREET_NUMBER
MISSING_PO_BOX_NUMBER
MISSING_POSTAL_CODE
INVALID_COUNTRY_CODE
UNSUPPORTED_COUNTRY_CODE
MISSING_SEARCH_EXPRESSION
Description: string

429 Too Many Requests

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

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"
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<MailboxDeliveryDates>
  <DeliveryDate>
    <DeliveryDate>2023-02-06</DeliveryDate>
    <DeliveryDate>2023-02-08</DeliveryDate>
    <DeliveryDate>2023-02-10</DeliveryDate>
    <DeliveryDate>2023-02-14</DeliveryDate>
    <DeliveryDate>2023-02-16</DeliveryDate>
    <DeliveryDate>2023-02-20</DeliveryDate>
  </DeliveryDate>
</MailboxDeliveryDates>

{
  "code": "INVALID_DATE_FORMAT",
  "description": "Invalid `from_date` date format. Should be formatted as ISO date (e.g. 2023-03-23) and not in the past"
}

<?xml version="1.0" encoding="UTF-8"?>
<!-- Example cannot be generated; root element name is undefined -->

{
  "code": "RATE_LIMIT_EXCEEDED",
  "description": "Request rate cannot exceed 40 requests per 1 second"
}

<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>RATE_LIMIT_EXCEEDED</Code>
  <Description>Request rate cannot exceed 40 requests per 1 second</Description>
</Error>

{
  "code": "INTERNAL_ERROR",
  "description": "An unexpected error occurred"
}

comments powered by Disqus

Supported Countries

Subscribe to updates

Endpoints

Get postal codes matching query

Request

header parameters

path parameters

query parameters

Responses

Schema

Schema

Schema

Schema

Response examples

Get postal code suggestions

Request

header parameters

path parameters

query parameters

Responses

Schema

Schema

Schema

Schema

Response examples

Get postal code

Request

header parameters

path parameters

Responses

Schema

Schema

Schema

Schema

Response examples

Get mailbox delivery dates at postal code

Request

header parameters

path parameters

query parameters

Responses

Schema

Schema

Schema

Schema

Response examples