Page Comparison

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 → https://www.di.no/addresshelper/

Content

Table of Contents

maxLevel	3
style	2

...

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

Info

Most clients can use our supplied frontend, you

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

Environments / Endpoints

TEST

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

PRODUCTION

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

...

Note

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

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.

...

Step 1 - Get Street Collections

Status

colour	Blue
title	GET

Code Block
/{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"

Expand

title	Details

Request

Query Parameters

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

colour	Green
title	STATUS 200

- application/JSON

Code Block

language	js

{
    "streets": [
        {
			"countryCode": String,
			"city": String",
            "streetName": String,           
            "streetIds": List<Integer> 	// A street has one or more id's
        }
    ],
	"totalResults": Integer
}

...

Step 2 - Get Street Numbers for Collection

Status

colour	Blue
title	GET

Code Block
/{countryCode}/streetNumberSearch/{streetIds}

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.

Expand

title	Details

Request

Query Parameters

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

colour	Green
title	STATUS 200

- application/JSON

Code Block

language	js

{
    "streetNumbers": [
		{
            "streetNo": Integer,
            "addressId": Integer,
            "entrance": String,						// Present if a building has several entrances, where the value is the entrance name
            "houseType": String, 					// See the following examples 
            "deliveryPointId": Integer,
            "postalCode": String,
            "duplicateNumberAndEntrance": Boolean,  // Some streets have several entrances on the same street number. When duplicateNumberAndAddress is true, the houseType should be used to separate them
            "latitude": Number, 
            "longitude": Number,
			"showHouseholds": Boolean 			    // True if households exists on houseType block
        },
		...
	]
}

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

Status

colour	Blue
title	GET

Code Block
/{countryCode}/address/{deliveryPointId}/floors

Returns the floors available at a deliveryPointId

Expand

title	Details

Request

Query Parameters

Parameter	Type	Example	Description
apiKey	string	myapikey	Please contact us if you don't know your API key.

Response

Status

colour	Green
title	STATUS 200

- application/JSON

Code Block

language	js

{
	{
       	"floorType": String, 		// The floor type represented by a single letter
       	"floorTypeName": String,	// The full word of the floor type (in Norwegian)
       	"floorNo": Integer
    },
    ...
}

Floor types:

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

...

Step 4 - Get Households on Floor

Status

colour	Blue
title	GET

Code Block
/{countryCode}/address/{deliveryPointId}/floor/{floorType}-{floorNo}/households

Returns the households on a given address and floor number.

...

Expand

title	Details

Request

Query Parameters

Parameter	Type	Example	Description
apiKey	string	myapikey	Please contact us if you don't know your API key.

Response

Status

colour	Green
title	STATUS 200

- application/JSON

Code Block

language	js

[
    {
        "flatNo": Integer,
        "deliveryPointId": Integer,
        "flatNoAlias": String
    },
    ...
]

...

Note
This functionality is deprecated and not maintained You may experience deviation in results from this service and other coverage and address check services

Status

colour	Blue
title	GET

Code Block
/{countryCode}/address/{deliveryPointId}/distributionSupport/{customerSystem}-{productName}

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

Expand

title	Details

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

colour	Green
title	STATUS 200

- application/JSON

Code Block

language	js

{
    "hasSupport": boolean,							// Defines if an address (deliveryPointId) has support for delivery. See remarks. 
    "coveredWeekdays": List<Boolean>,				// Shows the distribution support per weekday, starting on Monday. Does not consider holidays etc
    "distrDate": String, 							// "YYYY-MM-DD"
    "hasProductExclusion": Boolean,					// Set to true if the delivery point is excluded, all days. No delivery
    "deliveryPointId": Integer,						
    "keyDeviationWeekdays": Map<Integer, String> 	// Shows the key deviation per weekday, starting on Monday. The value indicates the issue
    "hasKeyDeviation": false,						// Tells whether there are any deviations in key access, eg. a key is broken. If true, the hasKeyDeviationWeekdays list can be used to determine which days are effected and how
    "deliveryPlace": "door"							// Where the user should pickup or put the packet. Default value "mailbox". See remarks
	"distrInfo": 									// Present if extendedTransportInfo is specified in the request
}

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

Note
This functionality is deprecated and not maintained You may experience deviation in results from this service and other coverage and address check services

Status

colour	Blue
title	GET

Code Block
/{countryCode}/distributionDates/{customerSystem}-{productName}/{fromDate}/{toDate}

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.

Expand

title	Details

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.

fromDate and toDate follows the format "YYYY-MM-DD"

Query Parameters

Parameter	Type	Example	Description
apiKey	string	myapikey	Please contact us if you don't know your API key.

Response

Status

colour	Green
title	STATUS 200

- application/JSON

Code Block

language	js

{
    "product": String,				// Product Name
    "distributions": List<String> 	// Strings with dates "YYYY-MM-DD"
}

Note: The value 2017-12-13 means the night from 12.-13. December

...

Expand

title	Distributions Response

Code Block

language	bash

{
    "product": "PROD",
    "distributions": [
        "2017-12-14",
        "2017-12-15",
        "2017-12-16",
        "2017-12-17",
        "2017-12-18",
        "2017-12-19",
        "2017-12-20",
        "2017-12-21",
        "2017-12-22",
        "2017-12-23"
    ]
}

Error response

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

Versions Compared

Old Version 16

New Version Current

Key

Environments / Endpoints

Authentication

Request Headers

Request body

Step 1 - Get Street Collections

Request

Query Parameters

Response

Step 2 - Get Street Numbers for Collection

Query Parameters

Response

Step 3 - Get Floors

Query Parameters

Response

Step 4 - Get Households on Floor

Request

Query Parameters

Response

Path Parameters

Query Parameters

Response

Step 6 - Distribution Dates

Path Parameters

Query Parameters

Response

Error response