Versions Compared

Old Version 16

changes.mady.by.user Linda Leung (Deactivated)

Saved on

compared with

New Version 17

changes.mady.by.user Ingrid Oliversen

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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

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

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
titleDetails

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

Code Block
languagejs
{
    "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
colourBlue
titleGET

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
titleDetails

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

Code Block
languagejs
{
    "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
colourBlue
titleGET

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

Returns the floors available at a deliveryPointId

Expand
titleDetails

Request

Query Parameters

Parameter

Type

Example

Description

apiKey

string

myapikey

Please contact us if you don't know your API key.

Response

Status
colourGreen
titleSTATUS 200
 - application/JSON

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

 See also hovedprinsipp for bolignummer i Norge

...

Step 4 - Get Households on Floor

Status
colourBlue
titleGET

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

Returns the households on a given address and floor number.

...

Expand
titleDetails

Request

Query Parameters

Parameter

Type

Example

Description

apiKey

string

myapikey

Please contact us if you don't know your API key.

Response

Status
colourGreen
titleSTATUS 200
 - application/JSON

Code Block
languagejs
[
    {
        "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
colourBlue
titleGET

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

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

Expand
titleDetails

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

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

(warning) If distrDate is unspecified, hasSupport will be true if there is coverage on the specified deliveryPointId (at least one day of the week).

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

(warning) 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

Status
colourBlue
titleGET

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
titleDetails


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

Code Block
languagejs
{
    "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
titleDistributions Response
Code Block
languagebash
{
    "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