DI Address Helper V2

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

Most clients can use our supplied frontend, you only need this if you want to create your own frontend-implementation.
See also SDK-documentation (Swagger)

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

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"

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 200 - application/JSON

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

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

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 200 - application/JSON

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

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

Returns the floors available at a deliveryPointId

Details

Request

Query Parameters

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

Response

STATUS 200 - application/JSON

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

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

Details

Request

Query Parameters

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

Response

STATUS 200 - application/JSON

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

Step 5 - Coverage / Distribution Support

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

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

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

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 200 - application/JSON

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

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

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 200 - application/JSON

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

Examples

Example 1: Get Street Collections

getStreetCollections Request

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

getStreetCollections Response

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

Example 2: Get Street Numbers For Collection

getStreetNumbersForCollection request

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

getStreetNumbersForCollection response

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

getFloors Request

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

getFloors Response

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

Example 4: Get Households on Floor

getHouseholdsOnFloor Request

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

getHouseholdsOnFloor Response

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

Example 5: Coverage / Distribution Support

distributionSupport Request

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

distributionSupport Response

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

Distributions Request

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

Distributions Response

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