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
OpenAPI document: https://api.bring.com/address/api-docs/postalcode

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

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

object

Required

array of objects

city

Required

City

string

county

County postal code is located in

string

latitude

If the postal code includes a PO Box (either exclusively i.e postal_code_type=PO_BOX or in combination with a street address i.e postal_code_type=COMBINED), the latitude returns WGS84 coordinates representing the precise location of the PO Box.

Conversely, if the postal code pertains solely to a street address i.e postal_code_type=STREET_ADDRESSES, the latitude returns WGS84 coordinates indicating the central point of the postal code.

string

longitude

If the postal code includes a PO Box (either exclusively i.e postal_code_type=PO_BOX or in combination with a street i.e address postal_code_type=COMBINED), the longitude returns WGS84 coordinates representing the precise location of the PO Box.

Conversely, if the postal code pertains solely to a street address i.e postal_code_type=STREET_ADDRESSES, the longitude returns WGS84 coordinates indicating the central point of the postal code.

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, This is deprecated. Use postal_code_type instead

boolean

postal_code

Required

Postal code

string

postal_code_type

Specifies the type of postal code associated with an address.

STREET_ADDRESSES - the postal code is used for street addresses
PO_BOX - the postal code is used for PO Boxes
COMBINED - the postal code is used for both street addresses and PO Boxes
SPECIAL_SERVICE - the postal code is used for special services
UNKNOWN - the type is unspecified or not recognized

string

Enum: STREET_ADDRESSES; PO_BOX; COMBINED; SPECIAL_SERVICE; UNKNOWN

postal_code_variations

Variations of this postal code used with this city. This is only used for Dutch postal codes.

array of strings

: string

special

Customer specific postal code. Only relevant for Norwegian postal codes. This is deprecated. Use postal_code_type instead

boolean

street_address_latitude

If the postal code includes a street address (either exclusively i.e postal_code_type=STREET_ADDRESSES or in combination with a PO Box i.e postal_code_type=COMBINED), the street_address_latitude returns WGS84 coordinates indicating the central point of the postal code.

Conversely, if the postal code pertains solely to a PO Box i.e postal_code_type=PO_BOX, the street_address_latitude returns null and is excluded from the response.

string

street_address_longitude

If the postal code includes a street address (either exclusively i.e postal_code_type=STREET_ADDRESSES or in combination with a PO Box i.e postal_code_type=COMBINED), the street_address_longitude returns WGS84 coordinates indicating the central point of the postal code.

Conversely, if the postal code pertains solely to a PO Box i.e postal_code_type=PO_BOX, the street_address_longitude returns null and is excluded from the response.

string

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

Conversely, if the postal code pertains solely to a street address i.e postal_code_type=STREET_ADDRESSES, the latitude returns WGS84 coordinates indicating the central point of the postal code.

string

Longitude

Conversely, if the postal code pertains solely to a street address i.e postal_code_type=STREET_ADDRESSES, the longitude returns WGS84 coordinates indicating the central point of the postal code.

string

Municipality

Municipality postal code is located in

string

MunicipalityId

Municipality id in which postal code is located

string

PostOfficeBox

Deprecated

Postal code is post office box, This is deprecated. Use postal_code_type instead

boolean

Code

Required

Postal code

string

PostalCodeType

Specifies the type of postal code associated with an address.

STREET_ADDRESSES - the postal code is used for street addresses
PO_BOX - the postal code is used for PO Boxes
COMBINED - the postal code is used for both street addresses and PO Boxes
SPECIAL_SERVICE - the postal code is used for special services
UNKNOWN - the type is unspecified or not recognized

string

Enum: STREET_ADDRESSES; PO_BOX; COMBINED; SPECIAL_SERVICE; UNKNOWN

Variations of this postal code used with this city. This is only used for Dutch postal codes.

array wrapped

Code: string

Special

Deprecated

Customer specific postal code. Only relevant for Norwegian postal codes. This is deprecated. Use postal_code_type instead

boolean

Street Address Latitude

Conversely, if the postal code pertains solely to a PO Box i.e postal_code_type=PO_BOX, the street_address_latitude returns null and is excluded from the response.

string

Street Address Longitude

If the postal code includes a street address (either exclusively i.e postal_code_type=STREET_ADDRESSES or in combination with a PO Box i.e postal_code_type=COMBINED), the street_address_longitude returns WGS84 coordinates indicating the central point of the postal code.

Conversely, if the postal code pertains solely to a PO Box i.e postal_code_type=PO_BOX, the street_address_longitude returns null and is excluded from the response.

string

400 Bad Request

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

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",
      "postal_code_type": "STREET_ADDRESSES"
    },
    {
      "city": "Son",
      "county": "Viken",
      "latitude": "59.5237",
      "longitude": "10.6862",
      "municipality": "Vestby",
      "municipalityId": "3019",
      "po_box": true,
      "postal_code": "1556",
      "postal_code_type": "STREET_ADDRESSES"
    }
  ]
}

{
  "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",
      "postal_code_type": "STREET_ADDRESSES"
    },
    {
      "city": "Son",
      "county": "Viken",
      "latitude": "59.5237",
      "longitude": "10.6862",
      "municipality": "Vestby",
      "municipalityId": "3019",
      "po_box": true,
      "postal_code": "1556",
      "postal_code_type": "STREET_ADDRESSES"
    },
    {
      "city": "Hølen",
      "county": "Viken",
      "latitude": "59.5237",
      "longitude": "10.6862",
      "municipality": "Vestby",
      "municipalityId": "3019",
      "po_box": false,
      "postal_code": "1540",
      "postal_code_type": "STREET_ADDRESSES"
    },
    {
      "city": "Hvitsten",
      "county": "Viken",
      "latitude": "59.5237",
      "longitude": "10.6862",
      "municipality": "Vestby",
      "municipalityId": "3019",
      "po_box": false,
      "postal_code": "1545",
      "postal_code_type": "STREET_ADDRESSES"
    }
  ]
}

<?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>
      <PostalCodeType>STREET_ADDRESSES</PostalCodeType>
    </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>
      <PostalCodeType>STREET_ADDRESSES</PostalCodeType>
    </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>
      <PostalCodeType>STREET_ADDRESSES</PostalCodeType>
    </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>
      <PostalCodeType>STREET_ADDRESSES</PostalCodeType>
    </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>
      <PostalCodeType>STREET_ADDRESSES</PostalCodeType>
    </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>
      <PostalCodeType>STREET_ADDRESSES</PostalCodeType>
    </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

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

object

Required

array of objects

city

Required

City

string

county

County postal code is located in

string

latitude

Conversely, if the postal code pertains solely to a street address i.e postal_code_type=STREET_ADDRESSES, the latitude returns WGS84 coordinates indicating the central point of the postal code.

string

longitude

Conversely, if the postal code pertains solely to a street address i.e postal_code_type=STREET_ADDRESSES, the longitude returns WGS84 coordinates indicating the central point of the postal code.

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, This is deprecated. Use postal_code_type instead

boolean

postal_code

Required

Postal code

string

postal_code_type

Specifies the type of postal code associated with an address.

STREET_ADDRESSES - the postal code is used for street addresses
PO_BOX - the postal code is used for PO Boxes
COMBINED - the postal code is used for both street addresses and PO Boxes
SPECIAL_SERVICE - the postal code is used for special services
UNKNOWN - the type is unspecified or not recognized

string

Enum: STREET_ADDRESSES; PO_BOX; COMBINED; SPECIAL_SERVICE; UNKNOWN

postal_code_variations

Variations of this postal code used with this city. This is only used for Dutch postal codes.

array of strings

: string

special

Customer specific postal code. Only relevant for Norwegian postal codes. This is deprecated. Use postal_code_type instead

boolean

street_address_latitude

Conversely, if the postal code pertains solely to a PO Box i.e postal_code_type=PO_BOX, the street_address_latitude returns null and is excluded from the response.

string

street_address_longitude

If the postal code includes a street address (either exclusively i.e postal_code_type=STREET_ADDRESSES or in combination with a PO Box i.e postal_code_type=COMBINED), the street_address_longitude returns WGS84 coordinates indicating the central point of the postal code.

Conversely, if the postal code pertains solely to a PO Box i.e postal_code_type=PO_BOX, the street_address_longitude returns null and is excluded from the response.

string

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

Conversely, if the postal code pertains solely to a street address i.e postal_code_type=STREET_ADDRESSES, the latitude returns WGS84 coordinates indicating the central point of the postal code.

string

Longitude

Conversely, if the postal code pertains solely to a street address i.e postal_code_type=STREET_ADDRESSES, the longitude returns WGS84 coordinates indicating the central point of the postal code.

string

Municipality

Municipality postal code is located in

string

MunicipalityId

Municipality id in which postal code is located

string

PostOfficeBox

Deprecated

Postal code is post office box, This is deprecated. Use postal_code_type instead

boolean

Code

Required

Postal code

string

PostalCodeType

Specifies the type of postal code associated with an address.

STREET_ADDRESSES - the postal code is used for street addresses
PO_BOX - the postal code is used for PO Boxes
COMBINED - the postal code is used for both street addresses and PO Boxes
SPECIAL_SERVICE - the postal code is used for special services
UNKNOWN - the type is unspecified or not recognized

string

Enum: STREET_ADDRESSES; PO_BOX; COMBINED; SPECIAL_SERVICE; UNKNOWN

Variations of this postal code used with this city. This is only used for Dutch postal codes.

array wrapped

Code: string

Special

Deprecated

Customer specific postal code. Only relevant for Norwegian postal codes. This is deprecated. Use postal_code_type instead

boolean

Street Address Latitude

Conversely, if the postal code pertains solely to a PO Box i.e postal_code_type=PO_BOX, the street_address_latitude returns null and is excluded from the response.

string

Street Address Longitude

If the postal code includes a street address (either exclusively i.e postal_code_type=STREET_ADDRESSES or in combination with a PO Box i.e postal_code_type=COMBINED), the street_address_longitude returns WGS84 coordinates indicating the central point of the postal code.

Conversely, if the postal code pertains solely to a PO Box i.e postal_code_type=PO_BOX, the street_address_longitude returns null and is excluded from the response.

string

400 Bad Request

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

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",
      "postal_code_type": "STREET_ADDRESSES"
    },
    {
      "city": "Son",
      "county": "Viken",
      "latitude": "59.5237",
      "longitude": "10.6862",
      "municipality": "Vestby",
      "municipalityId": "3019",
      "po_box": true,
      "postal_code": "1556",
      "postal_code_type": "STREET_ADDRESSES"
    }
  ]
}

<?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>
      <PostalCodeType>STREET_ADDRESSES</PostalCodeType>
    </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>
      <PostalCodeType>STREET_ADDRESSES</PostalCodeType>
    </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

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

Required

array of objects

city

Required

City

string

county

County postal code is located in

string

latitude

Conversely, if the postal code pertains solely to a street address i.e postal_code_type=STREET_ADDRESSES, the latitude returns WGS84 coordinates indicating the central point of the postal code.

string

longitude

Conversely, if the postal code pertains solely to a street address i.e postal_code_type=STREET_ADDRESSES, the longitude returns WGS84 coordinates indicating the central point of the postal code.

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, This is deprecated. Use postal_code_type instead

boolean

postal_code

Required

Postal code

string

postal_code_type

Specifies the type of postal code associated with an address.

STREET_ADDRESSES - the postal code is used for street addresses
PO_BOX - the postal code is used for PO Boxes
COMBINED - the postal code is used for both street addresses and PO Boxes
SPECIAL_SERVICE - the postal code is used for special services
UNKNOWN - the type is unspecified or not recognized

string

Enum: STREET_ADDRESSES; PO_BOX; COMBINED; SPECIAL_SERVICE; UNKNOWN

postal_code_variations

Variations of this postal code used with this city. This is only used for Dutch postal codes.

array of strings

: string

special

Customer specific postal code. Only relevant for Norwegian postal codes. This is deprecated. Use postal_code_type instead

boolean

street_address_latitude

Conversely, if the postal code pertains solely to a PO Box i.e postal_code_type=PO_BOX, the street_address_latitude returns null and is excluded from the response.

string

street_address_longitude

If the postal code includes a street address (either exclusively i.e postal_code_type=STREET_ADDRESSES or in combination with a PO Box i.e postal_code_type=COMBINED), the street_address_longitude returns WGS84 coordinates indicating the central point of the postal code.

Conversely, if the postal code pertains solely to a PO Box i.e postal_code_type=PO_BOX, the street_address_longitude returns null and is excluded from the response.

string

object

Required

array

object

City

Required

City

string

County

County postal code is located in

string

Latitude

Conversely, if the postal code pertains solely to a street address i.e postal_code_type=STREET_ADDRESSES, the latitude returns WGS84 coordinates indicating the central point of the postal code.

string

Longitude

Conversely, if the postal code pertains solely to a street address i.e postal_code_type=STREET_ADDRESSES, the longitude returns WGS84 coordinates indicating the central point of the postal code.

string

Municipality

Municipality postal code is located in

string

MunicipalityId

Municipality id in which postal code is located

string

PostOfficeBox

Deprecated

Postal code is post office box, This is deprecated. Use postal_code_type instead

boolean

Code

Required

Postal code

string

PostalCodeType

Specifies the type of postal code associated with an address.

STREET_ADDRESSES - the postal code is used for street addresses
PO_BOX - the postal code is used for PO Boxes
COMBINED - the postal code is used for both street addresses and PO Boxes
SPECIAL_SERVICE - the postal code is used for special services
UNKNOWN - the type is unspecified or not recognized

string

Enum: STREET_ADDRESSES; PO_BOX; COMBINED; SPECIAL_SERVICE; UNKNOWN

Variations of this postal code used with this city. This is only used for Dutch postal codes.

array wrapped

Code: string

Special

Deprecated

Customer specific postal code. Only relevant for Norwegian postal codes. This is deprecated. Use postal_code_type instead

boolean

Street Address Latitude

Conversely, if the postal code pertains solely to a PO Box i.e postal_code_type=PO_BOX, the street_address_latitude returns null and is excluded from the response.

string

Street Address Longitude

If the postal code includes a street address (either exclusively i.e postal_code_type=STREET_ADDRESSES or in combination with a PO Box i.e postal_code_type=COMBINED), the street_address_longitude returns WGS84 coordinates indicating the central point of the postal code.

Conversely, if the postal code pertains solely to a PO Box i.e postal_code_type=PO_BOX, the street_address_longitude returns null and is excluded from the response.

string

400 Bad Request

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

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_type": "UNKNOWN",
      "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",
      "postal_code_type": "STREET_ADDRESSES"
    },
    {
      "city": "Dresden",
      "county": "Sachsen",
      "latitude": "59.5237",
      "longitude": "10.6862",
      "municipalityId": "3019",
      "po_box": false,
      "postal_code": "01067",
      "postal_code_type": "STREET_ADDRESSES"
    },
    {
      "city": "Dresden friedrichstadt",
      "county": "Sachsen",
      "latitude": "59.5237",
      "longitude": "10.6862",
      "municipalityId": "3019",
      "po_box": false,
      "postal_code": "01067",
      "postal_code_type": "STREET_ADDRESSES"
    }
  ]
}

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

<?xml version="1.0" encoding="UTF-8"?>
<PostalCodes>
  <PostalCode>
    <PostalCode>
      <City>Echt</City>
      <County>Limburg</County>
      <Municipality>Echt-Susteren</Municipality>
      <Code>6101</Code>
      <PostalCodeType>UNKNOWN</PostalCodeType>
      <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>
      <PostalCodeType>STREET_ADDRESSES</PostalCodeType>
    </PostalCode>
    <PostalCode>
      <City>Dresden</City>
      <County>Sachsen</County>
      <Latitude>59.5237</Latitude>
      <Longitude>10.6862</Longitude>
      <MunicipalityId>3019</MunicipalityId>
      <Code>01067</Code>
      <PostalCodeType>STREET_ADDRESSES</PostalCodeType>
    </PostalCode>
    <PostalCode>
      <City>Dresden friedrichstadt</City>
      <County>Sachsen</County>
      <Latitude>59.5237</Latitude>
      <Longitude>10.6862</Longitude>
      <MunicipalityId>3019</MunicipalityId>
      <Code>01067</Code>
      <PostalCodeType>STREET_ADDRESSES</PostalCodeType>
    </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>
      <PostalCodeType>STREET_ADDRESSES</PostalCodeType>
    </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

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

delivery_dates

Required

List of coming mailbox delivery dates calculated from provided date

array of strings

: string

object

Required

List of coming mailbox delivery dates calculated from provided date

array

DeliveryDate: string

400 Bad Request

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

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

Postal Code API

Supported Countries

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

query 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