https://di.no/doc

DI Address Helper V2

Owned by Former user (Deleted)
Last updated: Mar 13, 2024 by Håvard Neset
10 min read

DI offers a service to compliment and validate official and non official addresses in Nordic countries - making it easier and more efficient for the end-user and distribution to deliver products. More information and examples can be found on the address helper webside → Addresshelper

Content

Setup

This is the documentation of the REST-API for DI Address Helper V2. It offers methods to lookup addresses in the Nordic countries.

Make sure you have the following information at hand before proceeding.

 

example

Comment

apiKey

wnfewnee(hw-ahoce

The key is provided when signing up for the service at DI Address Helper

customerSystem

STORE

Optional, used to receive possible distribution dates - this value is obtained from your contact person

product

PAKK

Optional, used to receive possible distribution dates - this value is obtained from your contact person

You only need this if you want to create your own frontend-implementation.

Environments / Endpoints

TEST

https://staging-ws.di.no/ws/json/addressHelper/v-2

PRODUCTION

https://ws.di.no/ws/json/addressHelper/v-2

 

Authentication

For this API the combination of referer and apiKey is used as authentication.
The apiKey provided when signing up for the service at DI Address Helper. The e-mail registered when signing up is responsible for approving domains used as referer.

When registering your account will be given a default number of requests each month. Remember to notify your contact person us to get a production-ready quota, and not just the testing-quota.

 

Making a Request

  • Remember to URI Encode. All requests MUST be in UTF-8 (not ISO-8859-1). Scandinavian characters must be encoded, e.g. æ → %c3%a6. Otherwise there will be no results when searching for a street name with these characters.

  • Beware that every request MUST contain a "referer"-header. The refererer must be a full URL (with schema), and the API-account will get an approval email each time a new domain is used.

Request Headers

Key

Value example

Comment

Key

Value example

Comment

referer

https://www.di.no

The value should specify the address/URI of the webpage that linked to the resource being requested. Mandatory.

NOTE: Must include schema (http/https)

Request body

Take a look at the examples to see how the requests and responses may look.

  • Most request are depending on the response of a previous request.

  • The apiKey parameter must be present in each request. 

Step 1 - Get Street Collections

GET

/{countryCode}/streetSearch/{streetName}

Returns a list of the streets that matches the streetName and countryCode. Note: street names may be filtered by city. Separate street name and city by a comma, i.e. "streetName,city"

Request

Query Parameters

Parameter

Type

Example

Description

Parameter

Type

Example

Description

apiKey

string

myapikey

Please contact us if you don't know your API key.

location

string

oslo

To show street name from relevant city first. If you want to show the streets in the user's city first in the result, you will have to use a service to find the city of the user's IP address. For common street names this is useful (i.e. Kirkegata, Skoleveien or Storgata)

limitToOfficial

boolean

true

If you want to limit the results to official Norwegian addresses (will eliminate duplicates). Default is false

limit

int

50

If you want to override the number of records to return. Default is 30, and max is 300.

Response

STATUS 200 - application/JSON





Step 2 - Get Street Numbers for Collection

GET

Returns the street numbers that are related to the streetIds provided in the request (ids are comma-delimited). The query parameter, streetNumber, can be used to filter the street numbers.

Request

Query Parameters

Parameter

Type

Example

Description

Parameter

Type

Example

Description

apiKey

string

myapikey

Please contact us if you don't know your API key.

streetNumber

whole number

10

Filter results by street number

limitToOfficial

boolean

true

If you want to limit the results to official Norwegian addresses (will eliminate duplicates). Default is false

limit

int

100

If you want to override the number of records to return. Default is 30, and max is 300.

Response

STATUS 200 - application/JSON

House types:

(E)nebolig     - detached house
(R)ekkehus   - row house
(B)lokk          - apartment building 
(F)orretning  - business
(H)ytte          - holiday house
(A)nnet         - other

Example address with duplicateNumberAndEntrance: Akersgata 45 (houseType B and F)



Step 3 - Get Floors

GET

Returns the floors available at a deliveryPointId

Request

Query Parameters

Parameter

Type

Example

Description

Parameter

Type

Example

Description

apiKey

string

myapikey

Please contact us if you don't know your API key.

Response

STATUS 200 - application/JSON

 Floor types:

(H)ovedetasje - main floor
(U)nderetasje - lower ground floor
(L)oft              - loft
(K)jeller          - basement

 See also hovedprinsipp for bolignummer i Norge



Step 4 - Get Households on Floor

GET

Returns the households on a given address and floor number.

By combining the floor type, floor number and flat number, the household can be represented following this standard (Norwegian article).

Request

Query Parameters

Parameter

Type

Example

Description

Parameter

Type

Example

Description

apiKey

string

myapikey

Please contact us if you don't know your API key.

Response

STATUS 200 - application/JSON



Step 5 - Coverage / Distribution Support

GET

Used to determine the distribution support for a given delivery point.

Request

Path Parameters

The customerSystem and productName is defined when signing up for the service. Please contact us if you don't know your customer system.

Query Parameters

Parameter

Type

Example

Description

Parameter

Type

Example

Description

apiKey

string

myapikey

Please contact us if you don't know your API key.

distrDate

string/date

2018-08-01

Check the available distribution on a given day. If not present, a general response is provided

extendedTransportInfo

boolean

true

Make detailed distribution information available (distrInfo in the response). Default is false. Note that the distrDate must be specified in the request to make use of this feature

name

string

lisa

This is an experimental feature, and is helpful when there is a mismatch between the user input and historical data

Response

STATUS 200 - application/JSON

 If distrDate is unspecified, hasSupport will be true if there is coverage on the specified deliveryPointId (at least one day of the week).

 If distrDate is unspecified, deliveryPlace will be set to the default value "mailbox". The deliveryPlace is depending on the distrDate as the value may vary on different weekdays. 

 If distrDate is specified, and hasSupport is false, it means that there is no support on the address on the given date. deliveryPlace will be set to the default value "mailbox". If hasSupport is false, the coveredWeekdays can be used to determine if there is coverage on other days of the week. 



Step 6 - Distribution Dates

GET

Gives a list of available distribution dates, independent of address. Note: if the date and delivery address (deliveryPointId) is determined, the distribution support should be used to confirm the date. 



Examples

Example 1: Get Street Collections

 

Example 2: Get Street Numbers For Collection

Example 3: Get Floors for Delivery Point Id

 

Example 4: Get Households on Floor

 

Example 5: Coverage / Distribution Support

 

Example 6: Distribution Dates

 

 


Error response

errorKey

Solution

errorKey

Solution

Unknown/blocked domain for given API-key. Get a key at https://www.di.no/addresshelper/

Approve domain from link sent to email registered for API Key