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

NOTE: Most clients can use our supplied frontend, you only need this if you want to create your own frontend-implementation.

...

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

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

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

...

Trouble Shooting

Why do I get error "Referrer missing"?

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.

}

Error response