Print Media Distribution coverage API Documentation

1 Overview
2 Authentication
3 Endpoints
- 3.1 1. Get Delivery Schedule by Product Short Name and Delivery Point
- 3.2 2. Get Delivery Schedule by Product Short Name and Address
4 Response Schema
- 4.1 Field Descriptions
5 Error Codes
6 OpenAPI (Swagger) documentation
7 Troubleshooting
8 Support

Overview

This API provides you with access to distribution coverage for print media products. You can retrieve detailed scheduling information based on delivery points or addresses using customer and product identifiers.

Base URL:
- DEV: https://print-media-distribution.dev.media.di.no
- PROD: https://print-media-distribution.prod.media.di.no
Stage: v1
Authentication: Requires an x-api-key header with each request.
Rate Limits: You can make up to 20,000 requests per day, with a burst limit of 200 requests and a rate limit of 100 requests per second.

Authentication

To use the API, include a valid API key in the x-api-key header of every request. Your API key is provided upon authorization. If you need a new or replacement key, contact the support team.

Example request header:

x-api-key: <your-api-key>

Endpoints

The API offers four GET endpoints to retrieve delivery schedules. Each endpoint requires the x-api-key header and returns JSON responses. Below are the details for each endpoint, including required parameters, response formats, and example requests.

1. Get Delivery Schedule by Product Short Name and Delivery Point

Method: GET
Path: /periodical/v1/delivery-schedule/by-short-name-delivery-point
Description: Retrieves the delivery schedule using short names for your customer system and product, plus a delivery point ID.
Query Parameters:
- customerSystemShortName (string, required): Your customer system short name.
- productShortName (string, required): The product short name.
- deliveryPointId (integer, required): The delivery point ID.
Response: Same as Response Schema.
Example Request:
curl -H "x-api-key: <your-api-key>" \ "https://print-media-distribution.media.di.no/periodical/v1/delivery-schedule/by-short-name-delivery-point?customerSystemShortName=XXX&productShortName=YYY&deliveryPointId=NNNNNNN"
Example Response:
{ "product": { "customerSystemShortName": "CSN", "customerSystemLongName": "Customer system name", "productShortName": "PRD", "productLongName": "Product name" }, "address": { "countryCode": "NO", "postalCode": 9999, "streetName": "Street name", "city": "City", "streetNo": 0 }, "deliveryPoint": { "deliveryPointId": 0, "isDeliveryPointAddressed": false, "excludedDayMatrixCompact": "" }, "distributions": [ { "distributionDayOfWeek": "MONDAY", "publicationDayOfWeek": "SATURDAY", "isProductMoved": true, "totalDaysMoved": 2, "distributionType": "DELIVERYGUIDE", "distributionCompany": { "distributionCompanyName": "DIST1", "distributionCompanyFullName": "Distribution company 1" }, "route": { "routeNumber": "000000", "routeName": "Route A", "addressedRoute": false } }, { "distributionDayOfWeek": "MONDAY", "publicationDayOfWeek": "SUNDAY", "isProductMoved": true, "totalDaysMoved": 1, "distributionType": "DELIVERYGUIDE", "distributionCompany": { "distributionCompanyName": "DIST1", "distributionCompanyFullName": "Distribution company 1" }, "route": { "routeNumber": "000000", "routeName": "Route A", "addressedRoute": false } }, { "distributionDayOfWeek": "TUESDAY", "publicationDayOfWeek": "MONDAY", "isProductMoved": true, "totalDaysMoved": 1, "distributionType": "DELIVERYGUIDE", "distributionCompany": { "distributionCompanyName": "DIST1", "distributionCompanyFullName": "Distribution company 1" }, "route": { "routeNumber": "000000", "routeName": "Route A", "addressedRoute": false } }, { "distributionDayOfWeek": "WEDNESDAY", "publicationDayOfWeek": "TUESDAY", "isProductMoved": true, "totalDaysMoved": 1, "distributionType": "DELIVERYGUIDE", "distributionCompany": { "distributionCompanyName": "DIST1", "distributionCompanyFullName": "Distribution company 1" }, "route": { "routeNumber": "000000", "routeName": "Route A", "addressedRoute": false } }, { "distributionDayOfWeek": "THURSDAY", "publicationDayOfWeek": "WEDNESDAY", "isProductMoved": true, "totalDaysMoved": 1, "distributionType": "DELIVERYGUIDE", "distributionCompany": { "distributionCompanyName": "DIST1", "distributionCompanyFullName": "Distribution company 1" }, "route": { "routeNumber": "000000", "routeName": "Route A", "addressedRoute": false } }, { "distributionDayOfWeek": "FRIDAY", "publicationDayOfWeek": "THURSDAY", "isProductMoved": true, "totalDaysMoved": 1, "distributionType": "DELIVERYGUIDE", "distributionCompany": { "distributionCompanyName": "DIST1", "distributionCompanyFullName": "Distribution company 1" }, "route": { "routeNumber": "000000", "routeName": "Route A", "addressedRoute": false } }, { "distributionDayOfWeek": "FRIDAY", "publicationDayOfWeek": "FRIDAY", "isProductMoved": false, "totalDaysMoved": 0, "distributionType": "POSTAL", "distributionCompany": { "distributionCompanyName": "DIST2", "distributionCompanyFullName": "Distribution company 2" }, "route": { "addressedRoute": true, "postalDeliveryType": "Regional" } } ] }

2. Get Delivery Schedule by Product Short Name and Address

Method: GET
Path: /periodical/v1/delivery-schedule/by-short-name-address
Description: Retrieves the delivery schedule using short names for your customer system and product, plus address details.
Query Parameters:
- customerSystemShortName (string, required): Your customer system short name.
- productShortName (string, required): The product short name.
- countryCode (string, required): The country code (e.g., "NO").
- postalCode (integer, required): The postal code.
- streetName (string, required): The street name.
- city (string, optional): The city.
- streetNo (integer, optional): The street number.
- entrance (string, optional): The entrance identifier.
- floorType (string, optional): The floor type (e.g., "Floor").
- floorNo (integer, optional): The floor number.
Response: Same as Response Schema.
Example Request:
curl -H "x-api-key: <your-api-key>" \ "https://print-media-distribution.media.di.no/periodical/v1/delivery-schedule/by-short-name-address?customerSystemShortName=XXX&productShortName=YYY&countryCode=NO&postalCode=4077&streetName=ULSNESVEIEN&city=HUNDV%C3%85G&streetNo=71"
Example Response: Same as above.

Response Schema

The delivery schedule response provides information about the product, address, delivery point, and distribution details.

{
  "product": {
    "customerSystemShortName": "string",
    "customerSystemLongName": "string",
    "productShortName": "string",
    "productLongName": "string"
  },
  "address": {
    "countryCode": "string",
    "postalCode": "integer",
    "streetName": "string",
    "city": "string",
    "streetNo": "integer",
    "entrance": "string",
    "floorType": "string",
    "floorNo": "integer",
    "flatNo": "integer",
    "houseType": "string",
    "description": "string",
    "boxType": "string"
  },
  "deliveryPoint": {
    "deliveryPointId": "integer",
    "isDeliveryPointAddressed": "boolean",
    "excludedDayMatrixCompact": "string"
  },
  "distributions": [
    {
      "distributionDayOfWeek": "string",
      "publicationDayOfWeek": "string",
      "isProductMoved": "boolean",
      "totalDaysMoved": "integer",
      "distributionType": "string",
      "distributionCompany": {
        "distributionCompanyName": "string",
        "distributionCompanyFullName": "string"
      },
      "route": {
        "routeNumber": "string",
        "routeName": "string",
        "addressedRoute": "boolean",
        "postalDeliveryType": "string"
      }
    }
  ]
}

Field Descriptions

The table below describes each field in the response schema, including its purpose and example values.

Field	Description	Example Value

Field	Description	Example Value
product.customerSystemShortName	The short name or code for your customer system, identifying the organization or system. Found in DI Publisher.
product.customerSystemLongName	The full name of your customer system, providing a descriptive title. Found in DI Publisher.
product.productShortName	The short name or code for the product, such as a newspaper or magazine.
product.productLongName	The full name of the product, providing a descriptive title.
address.countryCode	The two-letter ISO country code for the delivery address.	"NO"
address.postalCode	The postal code for the delivery address.	4077
address.streetName	The name of the street for the delivery address.	"ULSNESVEIEN"
address.city	The city for the delivery address.	"HUNDVÅG"
address.streetNo	The street number for the delivery address.	71
address.entrance	The entrance identifier for the delivery address, such as a building entrance code or letter. May be absent if not applicable.	“A“
address.floorType	The floor type for the delivery address. May be absent, if unknown or not applicable, or take the following values: H = Main floor U = Basement/lower floor L = Attic / Loft K = Cellar Part of the “Statens Kartverk” classification.	“H”
address.floorNo	The floor number for the delivery address. May be absent, if unknown or not applicable. Part of the “Statens Kartverk” classification.	3
address.flatNo	The flat number for the delivery address. May be absent, if unknown or not applicable. Part of the “Statens Kartverk” classification.	1
address.houseType	The house type for the delivery address. May be absent, if unknown or not applicable, or take these values: E = Single house R = Row House B = Block House / Apartment Building F = Business H = Cabin A = Other	“E”
address.description	Additional details about the delivery address, such as landmarks or delivery instructions. May be absent if not applicable.	“KIWI HUNDVÅG“
address.boxType	The type of mailbox or delivery box, if applicable. May be null or absent if not applicable, or take these values: INDIVIDUAL = Not a rack or shared box. Usually placed near customers RACK = Several boxes placed on one location (Kassestativ) SHARED_BOX = One box shared by different customers (Felleskasse) OUTSIDE_CORRIDOR = Open/outside corridor	“INDIVIDUAL“
deliveryPoint.deliveryPointId	A unique identifier for the delivery point, used to specify a location.	1368597
deliveryPoint.isDeliveryPointAddressed	Indicates whether the delivery point is addressed (true) or not (false).	false
deliveryPoint.excludedDayMatrixCompact	A string indicating days when delivery is not allowed (e.g., specific days of the week). Empty if no exclusions apply.	""
distributions[].distributionDayOfWeek	The day of the week the product is delivered (e.g., "MONDAY", "TUESDAY").	"MONDAY"
distributions[].publicationDayOfWeek	The day of the week the product is published, which may differ from the delivery day.	"SATURDAY"
distributions[].isProductMoved	Indicates whether the delivery day has been shifted from the publication day (true or false).	true
distributions[].totalDaysMoved	The number of days the delivery has been shifted from the publication day (0 if not moved).	2
distributions[].distributionType	The type of distribution method used (e.g., "DELIVERYGUIDE" for direct delivery, "POSTAL" for postal delivery).	"DELIVERYGUIDE"
distributions[].distributionCompany.distributionCompanyName	The short name or code for the company handling the distribution.	"HDVST"
distributions[].distributionCompany.distributionCompanyFullName	The full name of the company handling the distribution.	"HH Vest Stavanger"
distributions[].route.routeNumber	A unique identifier or code for the delivery route.	"029100"
distributions[].route.routeName	A descriptive name for the delivery route, often indicating the area or zone.	"B6 Buøy"
distributions[].route.addressedRoute	Indicates whether the route is addressed (true) or not (false).	false
distributions[].route.postalDeliveryType	The type of postal delivery, if applicable (e.g., "Regional"). Only included for postal distribution types like "POSTAL".	"Regional"

Error Codes

400 Bad Request: Indicates invalid or missing parameters. The details field in the response specifies the issue.
{ "message": "Invalid request parameters", "details": "customerSystemShortName is required" }
401 Unauthorized: Indicates an invalid or missing API key.
{ "message": "Unauthorized" }
403 Forbidden: Indicates access was denied.
{ "message": "Forbidden" }
429 Too Many Requests: Indicates you have exceeded the rate limit. Wait and try again later.

OpenAPI (Swagger) documentation

Troubleshooting

"Forbidden" Response:
- Verify that the x-api-key header is included and contains a valid key.
- Contact support to ensure your API key is active and correctly configured.
"Invalid Parameters":
- Check that all required query parameters are provided and formatted correctly.
- Review the details field in the 400 response for specific errors.
Rate Limit Exceeded:
- Reduce the frequency of your requests.
- Contact support if you need to discuss increasing your rate limits.
No Response or Timeout:
- Ensure you are using the correct base URL and stage (v1).
- Verify your network connectivity to the API endpoint.

Support

For assistance, reach out to the Distribution Innovation support team by creating a support ticket.

When requesting support, please provide your API key (obfuscated), the endpoint you are trying to access, and any error messages you receive

⚙️ Distribution coverage for print products