Address API
The Address API is used for validating and querying addresses, as well as getting suggestions in scenarios where the complete address is not known. It currently supports Norwegian addresses (street, place, post office box and postal place addresses). Addresses validated by this API are guaranteed to be valid, and it is therefore recommended to validate addresses that are used as input to Booking and Checkout related APIs.
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
Clients exceeding 40 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.
Returned format is controlled by the Accept
header. Supported values are application/json
and application/xml
. Default returned format is JSON.
Endpoints
https://api.bring.com/address/
Usage | Method | Endpoint |
---|---|---|
Get addresses matching query | GET |
/api/{country-code}/addresses
|
Get address | GET |
/api/{country-code}/addresses/{id}
|
Get street | GET |
/api/{country-code}/streets/{id}
|
Get available street numbers | GET |
/api/{country-code}/streets/{id}/numbers
|
Get street or place suggestions | GET |
/api/{country-code}/suggestions
|
Validate provided address | GET |
/api/{country-code}/validation
|
Get addresses matching query
/api/{country-code}/addresses
Fetches addresses matching provided filters.
Request
header parameters
-
X-Mybring-API-Uid
Required - Mybring login IDstring
-
X-Mybring-API-Key
Required - Your user's API keystring
-
Accept
- Desired output media typestringEnum:
application/json
application/xml
Default:"application/json"
path parameters
-
country-code
Required - Country codestringValue:
no
query parameters
-
street_or_place
- Street or place name. Required when querying for street and place address typesstringExample:
street_or_place=kolåsveien
-
address_type
Required - Address typestringEnum:
street
place
postal_place
po_box
-
po_box_number
- Post office box numberintegerExample:
po_box_number=1
-
po_box_facility
- Post office box facility namestringExample:
po_box_facility=Sentrum
-
postal_code
- Postal codestringExample:
postal_code=1555
-
city
- CitystringExample:
city=Son
-
street_number
- Street numberintegerExample:
street_number=9
-
letter
- House letterstringExample:
letter=B
-
page
- Page number for paginated resultsinteger
-
limit
- Number of results per page. Default 10. Max 10.integer
Responses
200 OK
-
Required
-
array
-
address_id
-
Unique address idstring
-
city
-
Citystring
-
county
-
County address is located instring
-
house_number
-
House numberinteger <int32>
-
letter
-
House letterstring
-
municipality
-
Municipality address is located instring
-
place
-
Place namestring
-
po_box_facility
-
Post office box facility namestring
-
po_box_number
-
Post office box numberinteger <int32>
-
postal_code
-
Postal codestring
-
street_name
-
Street namestring
-
type
-
Address typestringEnum:
STREET
PLACE
POSTAL_PLACE
PO_BOX
-
-
object
-
first
-
First pagestring
-
last
-
Last pagestring
-
next
-
Next pagestring
-
prev
-
Previous pagestring
-
self
-
Link to selfstring
-
total_hits
-
Total number of hitsinteger <int32>
-
-
Required
-
array
-
address_id
-
Unique address idstring
-
city
-
Citystring
-
county
-
County address is located instring
-
house_number
-
House numberinteger <int32>
-
letter
-
House letterstring
-
municipality
-
Municipality address is located instring
-
place
-
Place namestring
-
po_box_facility
-
Post office box facility namestring
-
po_box_number
-
Post office box numberinteger <int32>
-
postal_code
-
Postal codestring
-
street_name
-
Street namestring
-
type
-
Address typestringEnum:
STREET
PLACE
POSTAL_PLACE
PO_BOX
-
-
object
-
first
-
First pagestring
-
last
-
Last pagestring
-
next
-
Next pagestring
-
prev
-
Previous pagestring
-
self
-
Link to selfstring
-
total_hits
-
Total number of hitsinteger <int32>
-
400 Bad Request
-
code
-
stringEnum:
INVALID_COUNTRY
QUERY_PARAM_MISSING_OR_EMPTY
QUERY_PARAM_EMPTY
INVALID_PAGE_NUMBER
INVALID_LIMIT
LIMIT_LARGER_THAN_5
LIMIT_LARGER_THAN_10
LIMIT_LARGER_THAN_20
INVALID_POSTAL_CODE
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
-
description
-
string
-
code
-
stringEnum:
INVALID_COUNTRY
QUERY_PARAM_MISSING_OR_EMPTY
QUERY_PARAM_EMPTY
INVALID_PAGE_NUMBER
INVALID_LIMIT
LIMIT_LARGER_THAN_5
LIMIT_LARGER_THAN_10
LIMIT_LARGER_THAN_20
INVALID_POSTAL_CODE
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
-
description
-
string
429 Too Many Requests
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
500 Internal Server Error
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
Response examples
{
"addresses": [
{
"address_id": "1817301",
"city": "Son",
"county": "Viken",
"house_number": 9,
"municipality": "Vestby",
"postal_code": "1555",
"street_name": "Kolåsveien",
"type": "STREET"
},
{
"address_id": "1817302",
"city": "Son",
"county": "Viken",
"house_number": 10,
"municipality": "Vestby",
"postal_code": "1555",
"street_name": "Kolåsveien",
"type": "STREET"
}
],
"navigation": {
"self": "https://api.bring.com/address/api/no/addresses?street_or_place=kol%C3%A5sveien&address_type=street&postal_code=1555&city=Son&page=1",
"total_hits": 2
}
}
{
"code": "INVALID_ADDRESS_TYPE",
"description": "The 'address_type' query param requires one of the following values: [street, place, postal_place, po_box]"
}
{
"code": "INVALID_COUNTRY",
"description": "The provided country code is not supported"
}
{
"code": "INVALID_LETTER",
"description": "The 'letter' query param cannot be numeric"
}
{
"code": "INVALID_LIMIT",
"description": "The `limit` query param must be numeric"
}
{
"code": "INVALID_PAGE_NUMBER",
"description": "The 'page' query param must be numeric"
}
{
"code": "INVALID_POSTAL_CODE",
"description": "Invalid postal code format. Postal code must be numeric and consist of 4 digits"
}
{
"code": "INVALID_PO_BOX_NUMBER",
"description": "The 'po_box_number' query param must be numeric"
}
{
"code": "INVALID_STREET_NUMBER",
"description": "The 'street_number' query param must be numeric"
}
{
"code": "LIMIT_LARGER_THAN_10",
"description": "The `limit` query param cannot be greater than 10"
}
{
"code": "MISSING_ADDRESS_TYPE",
"description": "The 'address_type' query param cannot be null"
}
{
"code": "MISSING_POSTAL_CODE_OR_CITY_POSTAL_PLACE_ADDRESS",
"description": "Either 'postal_code' or 'city' query param is mandatory when providing an 'address_type' of postal place or post office box"
}
{
"code": "MISSING_STREET_OR_PLACE",
"description": "The 'street_or_place' query param is mandatory when providing an 'address_type' of street or place"
}
{
"code": "RATE_LIMIT_EXCEEDED",
"description": "Request rate cannot exceed 40 requests per 1 second"
}
{
"code": "INTERNAL_ERROR",
"description": "An unexpected error occurred"
}
Get address
/api/{country-code}/addresses/{id}
Fetches details for provided address id
Request
header parameters
-
X-Mybring-API-Uid
Required - Mybring login IDany
-
X-Mybring-API-Key
Required - Your user's API keyany
-
Accept
- Desired output media typestringEnum:
application/json
application/xml
Default:"application/json"
path parameters
-
country-code
Required - Country codestringValue:
no
-
id
Required - Id of address to fetchanyExample:
2264429
Responses
200 OK
-
address_id
-
Unique address idstring
-
city
-
Citystring
-
county
-
County address is located instring
-
house_number
-
House numberinteger <int32>
-
letter
-
House letterstring
-
municipality
-
Municipality address is located instring
-
place
-
Place namestring
-
po_box_facility
-
Post office box facility namestring
-
po_box_number
-
Post office box numberinteger <int32>
-
postal_code
-
Postal codestring
-
street_name
-
Street namestring
-
type
-
Address typestringEnum:
STREET
PLACE
POSTAL_PLACE
PO_BOX
-
address_id
-
Unique address idstring
-
city
-
Citystring
-
county
-
County address is located instring
-
house_number
-
House numberinteger <int32>
-
letter
-
House letterstring
-
municipality
-
Municipality address is located instring
-
place
-
Place namestring
-
po_box_facility
-
Post office box facility namestring
-
po_box_number
-
Post office box numberinteger <int32>
-
postal_code
-
Postal codestring
-
street_name
-
Street namestring
-
type
-
Address typestringEnum:
STREET
PLACE
POSTAL_PLACE
PO_BOX
400 Bad Request
-
code
-
stringEnum:
INVALID_COUNTRY
QUERY_PARAM_MISSING_OR_EMPTY
QUERY_PARAM_EMPTY
INVALID_PAGE_NUMBER
INVALID_LIMIT
LIMIT_LARGER_THAN_5
LIMIT_LARGER_THAN_10
LIMIT_LARGER_THAN_20
INVALID_POSTAL_CODE
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
-
description
-
string
-
code
-
stringEnum:
INVALID_COUNTRY
QUERY_PARAM_MISSING_OR_EMPTY
QUERY_PARAM_EMPTY
INVALID_PAGE_NUMBER
INVALID_LIMIT
LIMIT_LARGER_THAN_5
LIMIT_LARGER_THAN_10
LIMIT_LARGER_THAN_20
INVALID_POSTAL_CODE
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
-
description
-
string
404 Address not found
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
429 Too Many Requests
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
500 Internal Server Error
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
Response examples
{
"address_id": "3419922",
"city": "Sulitjelma",
"county": "Nordland",
"municipality": "Fauske",
"place": "Stormo",
"postal_code": "8230",
"type": "PLACE"
}
{
"address_id": "61899",
"city": "Oslo",
"county": "Oslo",
"municipality": "Oslo",
"po_box_facility": "Sentrum",
"po_box_number": 506,
"postal_code": "0105",
"type": "PO_BOX"
}
{
"address_id": "61899",
"city": "Oslo",
"county": "Oslo",
"municipality": "Oslo",
"po_box_facility": "Sentrum",
"po_box_number": 506,
"postal_code": "0105",
"type": "PO_BOX"
}
{
"address_id": "1817301",
"city": "Son",
"county": "Viken",
"house_number": 9,
"municipality": "Vestby",
"postal_code": "1555",
"street_name": "Kolåsveien",
"type": "STREET"
}
{
"code": "INVALID_COUNTRY",
"description": "The provided country code is not supported"
}
{
"code": "INVALID_LIMIT",
"description": "The `limit` query param must be numeric"
}
{
"code": "INVALID_PAGE_NUMBER",
"description": "The 'page' query param must be numeric"
}
{
"code": "LIMIT_LARGER_THAN_10",
"description": "The `limit` query param cannot be greater than 10"
}
{
"code": "NOT_FOUND",
"description": "Not found"
}
{
"code": "RATE_LIMIT_EXCEEDED",
"description": "Request rate cannot exceed 40 requests per 1 second"
}
{
"code": "INTERNAL_ERROR",
"description": "An unexpected error occurred"
}
Get street
/api/{country-code}/streets/{id}
Fetches details for provided street id
Request
header parameters
-
X-Mybring-API-Uid
Required - Mybring login IDstring
-
X-Mybring-API-Key
Required - Your user's API keystring
-
Accept
- Desired output media typestringEnum:
application/json
application/xml
Default:"application/json"
path parameters
-
country-code
Required - Country codestringValue:
no
-
id
Required - Id of street to fetchstringExample:
NO-0301-11704
Responses
200 OK
-
city
-
string
-
county
-
string
-
id
-
Street or address id. For addresses of type STREET, this will contain the street id. For other address types address id is returned.string
-
name
-
Street or place namestring
-
postal_code
-
string
-
type
-
Address typestringEnum:
STREET
PLACE
POSTAL_PLACE
PO_BOX
-
city
-
string
-
county
-
string
-
id
-
Street or address id. For addresses of type STREET, this will contain the street id. For other address types address id is returned.string
-
name
-
Street or place namestring
-
postal_code
-
string
-
type
-
Address typestringEnum:
STREET
PLACE
POSTAL_PLACE
PO_BOX
400 Bad Request
-
code
-
stringEnum:
INVALID_COUNTRY
QUERY_PARAM_MISSING_OR_EMPTY
QUERY_PARAM_EMPTY
INVALID_PAGE_NUMBER
INVALID_LIMIT
LIMIT_LARGER_THAN_5
LIMIT_LARGER_THAN_10
LIMIT_LARGER_THAN_20
INVALID_POSTAL_CODE
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
-
description
-
string
-
code
-
stringEnum:
INVALID_COUNTRY
QUERY_PARAM_MISSING_OR_EMPTY
QUERY_PARAM_EMPTY
INVALID_PAGE_NUMBER
INVALID_LIMIT
LIMIT_LARGER_THAN_5
LIMIT_LARGER_THAN_10
LIMIT_LARGER_THAN_20
INVALID_POSTAL_CODE
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
-
description
-
string
404 Street not found
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
429 Too Many Requests
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
500 Internal Server Error
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
Response examples
{
"city": "Sulitjelma",
"county": "Nordland",
"id": "3419922",
"name": "Stormo",
"postal_code": "8230",
"type": "PLACE"
}
{
"city": "Oslo",
"county": "Oslo",
"id": "NO-0301-11704",
"name": "Falsens gate",
"postal_code": "0556",
"type": "STREET"
}
{
"code": "INVALID_COUNTRY",
"description": "The provided country code is not supported"
}
{
"code": "INVALID_LIMIT",
"description": "The `limit` query param must be numeric"
}
{
"code": "INVALID_PAGE_NUMBER",
"description": "The 'page' query param must be numeric"
}
{
"code": "LIMIT_LARGER_THAN_10",
"description": "The `limit` query param cannot be greater than 10"
}
{
"code": "NOT_FOUND",
"description": "Not found"
}
{
"code": "RATE_LIMIT_EXCEEDED",
"description": "Request rate cannot exceed 40 requests per 1 second"
}
{
"code": "INTERNAL_ERROR",
"description": "An unexpected error occurred"
}
Get available street numbers
/api/{country-code}/streets/{id}/numbers
Returns a list of available street numbers for provided street id.
Request
header parameters
-
X-Mybring-API-Uid
Required - Mybring login IDstring
-
X-Mybring-API-Key
Required - Your user's API keystring
-
Accept
- Desired output media typestringEnum:
application/json
application/xml
Default:"application/json"
path parameters
-
country-code
Required - Country codestringValue:
no
-
id
Required - Street idstringExample:
NO-3019-04900
query parameters
-
page
- Page number for paginated resultsinteger
-
limit
- Number of results per page. Default 20. Max 20.integer
Responses
200 OK
-
object
-
first
-
First pagestring
-
last
-
Last pagestring
-
next
-
Next pagestring
-
prev
-
Previous pagestring
-
self
-
Link to selfstring
-
total_hits
-
Total number of hitsinteger <int32>
-
-
street_name
-
Street namestring
-
Required
-
array
-
address_id
-
Unique address idstring
-
formatted_number
-
House number (and letter) combinedstring
-
letter
-
House letterstring
-
number
-
House numberinteger <int32>
-
-
object
-
first
-
First pagestring
-
last
-
Last pagestring
-
next
-
Next pagestring
-
prev
-
Previous pagestring
-
self
-
Link to selfstring
-
total_hits
-
Total number of hitsinteger <int32>
-
-
street_name
-
Street namestring
-
Required
-
array
-
address_id
-
Unique address idstring
-
formatted_number
-
House number (and letter) combinedstring
-
letter
-
House letterstring
-
number
-
House numberinteger <int32>
-
400 Bad Request
-
code
-
stringEnum:
INVALID_COUNTRY
QUERY_PARAM_MISSING_OR_EMPTY
QUERY_PARAM_EMPTY
INVALID_PAGE_NUMBER
INVALID_LIMIT
LIMIT_LARGER_THAN_5
LIMIT_LARGER_THAN_10
LIMIT_LARGER_THAN_20
INVALID_POSTAL_CODE
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
-
description
-
string
-
code
-
stringEnum:
INVALID_COUNTRY
QUERY_PARAM_MISSING_OR_EMPTY
QUERY_PARAM_EMPTY
INVALID_PAGE_NUMBER
INVALID_LIMIT
LIMIT_LARGER_THAN_5
LIMIT_LARGER_THAN_10
LIMIT_LARGER_THAN_20
INVALID_POSTAL_CODE
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
-
description
-
string
404 Not Found
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
429 Too Many Requests
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
500 Internal Server Error
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
Response examples
{
"navigation": {
"self": "https://api.bring.com/address/api/no/streets/NO-3019-04900/numbers&page=1",
"total_hits": 4
},
"street_name": "Kolåsveien",
"street_numbers": [
{
"address_id": "1817301",
"formatted_number": "1",
"number": 1
},
{
"address_id": "1817302",
"formatted_number": "1A",
"letter": "A",
"number": 1
},
{
"address_id": "1817303",
"formatted_number": "1B",
"letter": "B",
"number": 1
},
{
"address_id": "1817304",
"formatted_number": "2",
"number": 2
}
]
}
{
"code": "INVALID_COUNTRY",
"description": "The provided country code is not supported"
}
{
"code": "INVALID_LIMIT",
"description": "The `limit` query param must be numeric"
}
{
"code": "INVALID_PAGE_NUMBER",
"description": "The 'page' query param must be numeric"
}
{
"code": "LIMIT_LARGER_THAN_20",
"description": "The `limit` query param cannot be greater than 20"
}
{
"code": "NOT_FOUND",
"description": "Not found"
}
{
"code": "RATE_LIMIT_EXCEEDED",
"description": "Request rate cannot exceed 40 requests per 1 second"
}
{
"code": "INTERNAL_ERROR",
"description": "An unexpected error occurred"
}
Get street or place suggestions
/api/{country-code}/suggestions
Returns a list of streets and places matching input query. The following address types are supported: - Street address - Place Depending on the returned suggestion type, the id will differ. Returned suggestions are identified by either an street_id or an address_id. Suggestions of type STREET are identified with street_id which is an unique identifier for a street. To obtain an address_id you will need street number as well. Suggestions of type PLACE are identified with address_id, which are unique addresses and does not support street numbers.
Request
header parameters
-
X-Mybring-API-Uid
Required - Mybring login IDstring
-
X-Mybring-API-Key
Required - Your user's API keystring
-
Accept
- Desired output media typestringEnum:
application/json
application/xml
Default:"application/json"
path parameters
-
country-code
Required - Country codestringValue:
no
query parameters
-
q
Required - Street or place name to filter forstringExamples:
Partial street or place name
Will return all matching streets or places containing this name
q=kolås
Street or place name
Will return all matching streets or places with this name
q=kolåsveien
Street or place name with city
If city is known you may supply it (prefixed by ,) to narrow the search
q=kolås, son
Street or place name with postal code
If postal code is known you may supply it (prefixed by ,) to narrow the search
q=kolås, 1555
-
page
- Page number for paginated resultsinteger
-
limit
- Number of results per page. Default 10. Max 10.integer
Responses
200 OK
-
object
-
first
-
First pagestring
-
last
-
Last pagestring
-
next
-
Next pagestring
-
prev
-
Previous pagestring
-
self
-
Link to selfstring
-
total_hits
-
Total number of hitsinteger <int32>
-
-
Required
-
array
-
city
-
string
-
county
-
string
-
id
-
Street or address id. For addresses of type STREET, this will contain the street id. For other address types address id is returned.string
-
name
-
Street or place namestring
-
postal_code
-
string
-
type
-
Address typestringEnum:
STREET
PLACE
POSTAL_PLACE
PO_BOX
-
-
object
-
first
-
First pagestring
-
last
-
Last pagestring
-
next
-
Next pagestring
-
prev
-
Previous pagestring
-
self
-
Link to selfstring
-
total_hits
-
Total number of hitsinteger <int32>
-
-
Required
-
array
-
city
-
string
-
county
-
string
-
id
-
Street or address id. For addresses of type STREET, this will contain the street id. For other address types address id is returned.string
-
name
-
Street or place namestring
-
postal_code
-
string
-
type
-
Address typestringEnum:
STREET
PLACE
POSTAL_PLACE
PO_BOX
-
400 Bad Request
-
code
-
stringEnum:
INVALID_COUNTRY
QUERY_PARAM_MISSING_OR_EMPTY
QUERY_PARAM_EMPTY
INVALID_PAGE_NUMBER
INVALID_LIMIT
LIMIT_LARGER_THAN_5
LIMIT_LARGER_THAN_10
LIMIT_LARGER_THAN_20
INVALID_POSTAL_CODE
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
-
description
-
string
-
code
-
stringEnum:
INVALID_COUNTRY
QUERY_PARAM_MISSING_OR_EMPTY
QUERY_PARAM_EMPTY
INVALID_PAGE_NUMBER
INVALID_LIMIT
LIMIT_LARGER_THAN_5
LIMIT_LARGER_THAN_10
LIMIT_LARGER_THAN_20
INVALID_POSTAL_CODE
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
-
description
-
string
429 Too Many Requests
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
500 Internal Server Error
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
Response examples
{
"navigation": {
"self": "https://api.bring.com/address/api/no/suggestions?page=1",
"total_hits": 2
},
"streets_and_places": [
{
"city": "Oslo",
"county": "Oslo",
"id": "NO-0301-11704",
"name": "Falsens gate",
"postal_code": "0556",
"type": "STREET"
},
{
"city": "Sulitjelma",
"county": "Nordland",
"id": "3419922",
"name": "Stormo",
"postal_code": "8230",
"type": "PLACE"
}
]
}
{
"code": "INVALID_COUNTRY",
"description": "The provided country code is not supported"
}
{
"code": "INVALID_LIMIT",
"description": "The `limit` query param must be numeric"
}
{
"code": "INVALID_PAGE_NUMBER",
"description": "The 'page' query param must be numeric"
}
{
"code": "INVALID_POSTAL_CODE",
"description": "Invalid postal code format. Postal code must be numeric and consist of 4 digits"
}
{
"code": "LIMIT_LARGER_THAN_10",
"description": "The `limit` query param cannot be greater than 10"
}
{
"code": "QUERY_PARAM_MISSING_OR_EMPTY",
"description": "The 'q' query param cannot be null or empty"
}
{
"code": "RATE_LIMIT_EXCEEDED",
"description": "Request rate cannot exceed 40 requests per 1 second"
}
{
"code": "INTERNAL_ERROR",
"description": "An unexpected error occurred"
}
Validate provided address
/api/{country-code}/validation
Will attempt to find a matching address. If no exact match is found, a list of possible reasons are returned along with close matching alternative suggestions (if found).
Request
header parameters
-
X-Mybring-API-Uid
Required - Mybring login IDstring
-
X-Mybring-API-Key
Required - Your user's API keystring
-
Accept
- Desired output media typestringEnum:
application/json
application/xml
Default:"application/json"
path parameters
-
country-code
Required - Country codestringValue:
no
query parameters
-
street_or_place
- Street or place name. Required when querying for street and place address typesstringExample:
street_or_place=kolåsveien
-
address_type
Required - Address typestringEnum:
street
place
postal_place
po_box
-
po_box_number
- Post office box numberintegerExample:
po_box_number=1
-
po_box_facility
- Post office box facility namestringExample:
po_box_facility=Sentrum
-
postal_code
Required - Postal codestringExample:
postal_code=1555
-
city
- City. Required for postal place addressesstringExample:
city=Son
-
street_number
- Street number. Required for street addressesintegerExample:
street_number=9
-
letter
- House letterstringExample:
letter=B
Responses
200 OK
-
object
-
address_id
-
Unique address idstring
-
city
-
Citystring
-
county
-
County address is located instring
-
house_number
-
House numberinteger <int32>
-
letter
-
House letterstring
-
municipality
-
Municipality address is located instring
-
place
-
Place namestring
-
po_box_facility
-
Post office box facility namestring
-
po_box_number
-
Post office box numberinteger <int32>
-
postal_code
-
Postal codestring
-
street_name
-
Street namestring
-
type
-
Address typestringEnum:
STREET
PLACE
POSTAL_PLACE
PO_BOX
-
-
Possible reasons why provided address was not foundarray
-
code
-
Validation error codestringEnum:
HOUSE_NUMBER_DOES_NOT_EXIST
HOUSE_LETTER_DOES_NOT_EXIST
STREET_NAME_DOES_NOT_EXIST
PLACE_DOES_NOT_EXIST
ADDRESS_NOT_FOUND
INCORRECT_CITY
PO_BOX_NUMBER_DOES_NOT_EXIST
PO_BOX_FACILITY_DOES_NOT_EXIST
-
description
-
Validation error descriptionstring
-
-
Alternate address suggestionsarray
-
address_id
-
Unique address idstring
-
city
-
Citystring
-
county
-
County address is located instring
-
house_number
-
House numberinteger <int32>
-
letter
-
House letterstring
-
municipality
-
Municipality address is located instring
-
place
-
Place namestring
-
po_box_facility
-
Post office box facility namestring
-
po_box_number
-
Post office box numberinteger <int32>
-
postal_code
-
Postal codestring
-
street_name
-
Street namestring
-
type
-
Address typestringEnum:
STREET
PLACE
POSTAL_PLACE
PO_BOX
-
-
valid
Required -
Address is validboolean
-
object
-
address_id
-
Unique address idstring
-
city
-
Citystring
-
county
-
County address is located instring
-
house_number
-
House numberinteger <int32>
-
letter
-
House letterstring
-
municipality
-
Municipality address is located instring
-
place
-
Place namestring
-
po_box_facility
-
Post office box facility namestring
-
po_box_number
-
Post office box numberinteger <int32>
-
postal_code
-
Postal codestring
-
street_name
-
Street namestring
-
type
-
Address typestringEnum:
STREET
PLACE
POSTAL_PLACE
PO_BOX
-
-
Possible reasons why provided address was not foundarray
-
code
-
Validation error codestringEnum:
HOUSE_NUMBER_DOES_NOT_EXIST
HOUSE_LETTER_DOES_NOT_EXIST
STREET_NAME_DOES_NOT_EXIST
PLACE_DOES_NOT_EXIST
ADDRESS_NOT_FOUND
INCORRECT_CITY
PO_BOX_NUMBER_DOES_NOT_EXIST
PO_BOX_FACILITY_DOES_NOT_EXIST
-
description
-
Validation error descriptionstring
-
-
Alternate address suggestionsarray
-
address_id
-
Unique address idstring
-
city
-
Citystring
-
county
-
County address is located instring
-
house_number
-
House numberinteger <int32>
-
letter
-
House letterstring
-
municipality
-
Municipality address is located instring
-
place
-
Place namestring
-
po_box_facility
-
Post office box facility namestring
-
po_box_number
-
Post office box numberinteger <int32>
-
postal_code
-
Postal codestring
-
street_name
-
Street namestring
-
type
-
Address typestringEnum:
STREET
PLACE
POSTAL_PLACE
PO_BOX
-
-
valid
Required -
Address is validboolean
400 Bad Request
-
code
-
stringEnum:
INVALID_COUNTRY
QUERY_PARAM_MISSING_OR_EMPTY
QUERY_PARAM_EMPTY
INVALID_PAGE_NUMBER
INVALID_LIMIT
LIMIT_LARGER_THAN_5
LIMIT_LARGER_THAN_10
LIMIT_LARGER_THAN_20
INVALID_POSTAL_CODE
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
-
description
-
string
-
code
-
stringEnum:
INVALID_COUNTRY
QUERY_PARAM_MISSING_OR_EMPTY
QUERY_PARAM_EMPTY
INVALID_PAGE_NUMBER
INVALID_LIMIT
LIMIT_LARGER_THAN_5
LIMIT_LARGER_THAN_10
LIMIT_LARGER_THAN_20
INVALID_POSTAL_CODE
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
-
description
-
string
429 Too Many Requests
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
500 Internal Server Error
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
-
code
-
stringEnum:
INTERNAL_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
-
description
-
string
Response examples
{
"reasons": [
{
"code": "ADDRESS_NOT_FOUND",
"description": "No matching address found, and no alternative suggestions available"
}
],
"valid": false
}
{
"reasons": [
{
"code": "INCORRECT_CITY",
"description": "Incorrect city"
}
],
"suggestions": [
{
"address_id": "1817301",
"city": "Son",
"county": "Viken",
"house_number": 9,
"municipality": "Vestby",
"postal_code": "1555",
"street_name": "Kolåsveien",
"type": "STREET"
}
],
"valid": false
}
{
"reasons": [
{
"code": "HOUSE_LETTER_DOES_NOT_EXIST",
"description": "Requested house letter does not exist"
}
],
"suggestions": [
{
"address_id": "1817301",
"city": "Son",
"county": "Viken",
"house_number": 9,
"municipality": "Vestby",
"postal_code": "1555",
"street_name": "Kolåsveien",
"type": "STREET"
}
],
"valid": false
}
{
"reasons": [
{
"code": "HOUSE_NUMBER_DOES_NOT_EXIST",
"description": "Requested house number does not exist"
}
],
"suggestions": [
{
"address_id": "1817301",
"city": "Son",
"county": "Viken",
"house_number": 9,
"municipality": "Vestby",
"postal_code": "1555",
"street_name": "Kolåsveien",
"type": "STREET"
}
],
"valid": false
}
{
"reasons": [
{
"code": "PLACE_DOES_NOT_EXIST",
"description": "Requested place not found"
}
],
"suggestions": [
{
"address_id": "3419922",
"city": "Sulitjelma",
"county": "Nordland",
"municipality": "Fauske",
"place": "Stormo",
"postal_code": "8230",
"type": "PLACE"
}
],
"valid": false
}
{
"reasons": [
{
"code": "PO_BOX_FACILITY_DOES_NOT_EXIST",
"description": "Requested post office box facility does not exist"
}
],
"suggestions": [
{
"address_id": "61899",
"city": "Oslo",
"county": "Oslo",
"municipality": "Oslo",
"po_box_facility": "Sentrum",
"po_box_number": 506,
"postal_code": "0105",
"type": "PO_BOX"
}
],
"valid": false
}
{
"reasons": [
{
"code": "PO_BOX_NUMBER_DOES_NOT_EXIST",
"description": "Requested post office box number does not exist"
}
],
"suggestions": [
{
"address_id": "61899",
"city": "Oslo",
"county": "Oslo",
"municipality": "Oslo",
"po_box_facility": "Sentrum",
"po_box_number": 506,
"postal_code": "0105",
"type": "PO_BOX"
}
],
"valid": false
}
{
"reasons": [
{
"code": "STREET_NAME_DOES_NOT_EXIST",
"description": "Requested street name not found"
}
],
"suggestions": [
{
"address_id": "1817301",
"city": "Son",
"county": "Viken",
"house_number": 9,
"municipality": "Vestby",
"postal_code": "1555",
"street_name": "Kolåsveien",
"type": "STREET"
}
],
"valid": false
}
{
"match": {
"address_id": "1817301",
"city": "Son",
"county": "Viken",
"house_number": 9,
"municipality": "Vestby",
"postal_code": "1555",
"street_name": "Kolåsveien",
"type": "STREET"
},
"valid": true
}
{
"code": "INVALID_ADDRESS_TYPE",
"description": "The 'address_type' query param requires one of the following values: [street, place, postal_place, po_box]"
}
{
"code": "INVALID_COUNTRY",
"description": "The provided country code is not supported"
}
{
"code": "INVALID_LETTER",
"description": "The 'letter' query param cannot be numeric"
}
{
"code": "INVALID_PO_BOX_NUMBER",
"description": "The 'po_box_number' query param must be numeric"
}
{
"code": "INVALID_STREET_NUMBER",
"description": "The 'street_number' query param must be numeric"
}
{
"code": "MISSING_ADDRESS_TYPE",
"description": "The 'address_type' query param cannot be null"
}
{
"code": "MISSING_CITY_POSTAL_PLACE_ADDRESS",
"description": "The 'city' query param is mandatory when providing an 'address_type' postal place"
}
{
"code": "MISSING_OR_INVALID_POSTAL_CODE",
"description": "The 'postal_code' query param is missing or has an invalid postal code format. Postal code must be numeric and consist of 4 digits"
}
{
"code": "MISSING_PO_BOX_NUMBER",
"description": "'po_box_number' query param is mandatory when providing a po_box 'address_type'"
}
{
"code": "MISSING_STREET_NUMBER",
"description": "'street_number' query param is mandatory when providing a street 'address_type'"
}
{
"code": "MISSING_STREET_OR_PLACE",
"description": "The 'street_or_place' query param is mandatory when providing an 'address_type' of street or place"
}
{
"code": "RATE_LIMIT_EXCEEDED",
"description": "Request rate cannot exceed 40 requests per 1 second"
}
{
"code": "INTERNAL_ERROR",
"description": "An unexpected error occurred"
}