Versions Compared

Key

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

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

Table of Contents
maxLevel3
style2

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

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
Most clients can use our supplied frontend, you

You only need this if you want to create your own frontend-implementation.

  • See also SDK-documentation (Swagger)

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


    Step 5 - Coverage / Distribution Support

    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. 

    6 - Distribution Dates

    is coverage on other days of the week. 


    Step 6 - Distribution Dates

    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}/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