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.NOTE: Most clients can use our supplied frontend, you only need this if you want to create your own frontend-implementation.

Setup

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

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

Swagger DOC

See also SDK-documentation (Swagger)

...

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

Request Headers

Encoding

...

Request body

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}

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

...

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
}

...

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.