...

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

Setup

Make sure you have the following information at hand before proceeding

...

The key provided when signing up for the service. Please contact us if you don't know your API key. Needed for all requests, see the examples.

 Remember to contact us to get a production-ready quota, and not just the testing-quota (or you might get an error message when your quota is used for the month)

...

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.

Environments / Endpoints

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

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

Swagger DOC

See also SDK-documentation (Swagger)

Making a Request

Request Headers

...

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)

Encoding

...

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

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"

Response

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

Composing a Request

Take a look at the examples to see how the requests and responses may look. Note that the apiKey parameter must be present in each request. 

Step 1 - Get Street Collections

...

...

/{countryCode}/streetSearch/{streetName}

Request Headers

Request body

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

Step 1 - Get Street Collections

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

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

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

{
    "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
        },
		...
	]
}

Step 3 - Get Floors

/{countryCode}/address/{deliveryPointId}/floors

Returns the floors available at a deliveryPointId

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

Step 4 - Get Households on Floor

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

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

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

...

Step 5 - Coverage / Distribution Support

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

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

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

...

Step 6 - Distribution Dates

...

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

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

...

Examples

Example 1: Get Street Collections

# NOTE: Remember to concatenate the URL/QueryString - we have spread it over several lines for better readability

curl 'https://ws.di.no/ws/json/addressHelper/v-2/NO/streetSearch/akersgata?apiKey=<your-api-key>'
-H 'referer: <your-web-address>'

...

...

{
    "totalResults": 2,
    "streets": [
        {
            "streetName": "AKERSGATA",
            "isAliasMatch": "0",
            "city": "OSLO",
            "countryCode": "NO",
            "streetIds": [
                14881,
                15003
            ]
        }
    ]
}

Example 2: Get Street Numbers For Collection

# NOTE: Remember to concatenate the URL/QueryString - we have spread it over several lines for better readability

curl 'https://ws.di.no/ws/json/addressHelper/v-2/NO/streetNumberSearch/14881,15003?apiKey=<your-api-key>&streetNumber=1'
-H 'referer: <your-web-address>'

{
    "streetNumbers": [
		{
            "streetNo": 1,
            "addressId": 308371,
            "entrance": null,
            "houseType": "F",
            "deliveryPointId": 523325,
            "postalCode": "0158",
            "duplicateNumberAndEntrance": false,
            "latitude": 59.910698,
            "longitude": 10.738707

,
			"showHouseholds": false
        },
        {
            "streetNo": 11,
            "addressId": 308376,
            "entrance": null,
            "houseType": "F",
            "deliveryPointId": 523334,
            "postalCode": "0158",
            "duplicateNumberAndEntrance": false,
            "latitude": 59.911144,
            "longitude": 10.739116,
			"showHouseholds": false
        },
		...
	]
}

Example 3: Get Floors for Delivery Point Id

# NOTE: Remember to concatenate the URL/QueryString - we have spread it over several lines for better readability

curl 'https://ws.di.no/ws/json/addressHelper/v-2/NO/address/431980/floors?apiKey=<your-api-key>'
-H 'referer: <your-web-address>'

...

...

{
	{
       	"floorType": "H",
       	"floorTypeName": null,
       	"floorNo": 1
    },
    {
       	"floorType": "H",
       	"floorTypeName": null,
       	"floorNo": 2
    }
}

Example 4: Get Households on Floor

# NOTE: Remember to concatenate the URL/QueryString - we have spread it over several lines for better readability

curl 'https://ws.di.no/ws/json/addressHelper/v-2/NO/address/1220170/floor/H-3?apiKey=<your-api-key>'
-H 'referer: <your-web-address>'

...

...

[
    {
        "flatNo": 1,
        "deliveryPointId": 2688072,
        "flatNoAlias": null
    },
    {
        "flatNo": 2,
        "deliveryPointId": 2688073,
        "flatNoAlias": null
    }
]

Example 5: Coverage / Distribution Support

# NOTE: Remember to concatenate the URL/QueryString - we have spread it over several lines for better readability

curl 'https://ws.di.no/ws/json/addressHelper/v-2/NO/address/508042/distributionSupport/CS-PROD?apiKey=<your-api-key>'
-H 'referer: <your-web-address>'

...

...

{
    "hasSupport": true,
    "coveredWeekdays": [
        true,
        true,
        true,
        true,
        true,
        true,
        true
    ],
    "distrDate": "2016-12-14",
    "hasProductExclusion": false,
    "deliveryPointId": 508042,
    "keyDeviationWeekdays": [
        null,
        null,
        null,
        null,
        null,
        null,
        null
    ],
    "hasKeyDeviation": false,
    "deliveryPlace": "door"
}

Example 6: Distribution Dates

# NOTE: Remember to concatenate the URL/QueryString - we have spread it over several lines for better readability

curl 'https://ws.di.no/ws/json/addressHelper/v-2/NO/distributionDates/CS-PROD/2017-12-13/2017-12-23?apiKey=<your-api-key>'
-H 'referer: <your-web-address>'

...

...

...

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

Trouble Shooting

Why do I get error "Referrer missing"?

...