Tutorial: Shipment delivery time estimates

Get delivery time estimates for your shipments

Estimation API provides a REST interface for querying delivery estimates for parcels. The interface can be used for querying the estimated delivery time for a given destination postal code and product. Estimation is based on product and area specific schedules for each logistic phase.

Please see the full API description at https://api.posti.fi/estimation/api/index.html

Example: Postal Parcel from Helsinki to Sodankylä

This delivery estimate can be queried with URL:

https://api.posti.fi/estimation/v1/00100/FI/99710/FI/2103?time=2014-10-03T09:00:00.000%2B0300

Response:

{
  "deliveryTime" : "2014-10-07T16:00:00.000+03:00"
}     

In this case, the estimate assumes that the parcel is available for pickup from Posti delivery office in Helsinki, 00100 at 9:00 on October 3rd, which is a Friday. Product code for Postal Parcel is 2103 (Economy 16).

Parcels must be dropped of by 17:00 to make it for transportation at the same day. Parcels from Helsinki to Sodankylä are promised to be delivered on the second work day, and because of the weekend the delivery is on Tuesday.

Example 1

Example: Parcel to Doorstep from Tampere to Helsinki, Saturday Delivery

This delivery estimate can be queried with URL:

https://api.posti.fi/estimation/v1/00100/FI/33100/FI/2102?time=2014-10-03T13:30:00.000%2B0300&logisticPhase=PICKED_UP&service=3106

Response:

{
  "deliveryTime" : "2014-10-04T09:00:00.000+03:00"
}     

In this case, the estimate assumes that the parcel is picked up by Posti from Tampere 33100 Helsinki, 00100 at 13:30 on October 3rd, which is a Friday. Note that this assumes that the customer has agreed upon pick up with Posti accordingly.

Product code for Parcel to Doorstep is 2102, and additional services 3106 indicates Saturday delivery.

Example 2

API description

Please see the full API description at https://api.posti.fi/estimation/api/index.html

The parameters relevant for customers are the following:

Parameter Description Type Data
startLocation Postal code for source address. E.g. 00100 path string
startCountry ISO Country Code, 2 Digit. E.g FI, SE, GB path string
toLocation Postal code for destination address. E.g. 00100 path string
toCountry ISO Country Code, 2 Digit. E.g FI, SE, GB path string
product Product id. E.g 2101 path string
customer Customer id or contract id query string
time ISO Date time when delivery will be or was in start location.E.g 2014-05-16T14:31:14.558Z. query string
logisticPhase Item event type. The last event of item.Values AVAILABLE_FOR_PICKUP, PICKED_UP, SORTED, IN_TRANSPORT, IN_DELIVERY query string
service Additional services for product, e.g. 3106 query string

Logistic Phases

Phase Description
AVAILABLE_FOR_PICKUP The parcel has been dropped to a Posti delivery office to be picked up for transport. The delivery office for the postal code is resolved by the API. Note that the based on time the parcel may not make it to transport the same day.
PICKED_UP The parcel has been picked up by Posti for transport or delivery. Note that this assumes that the customer has agreed the collect schedule with Posti accordingly.
SORTED Posti has sorted the parcel in a sorting center. In this case the start location must be one of Posti’s logistic centers or sorting centers.As a API parameter this is mainly relevant for Posti internal use.
IN_TRANSPORT Posti has sorted the parcel and the parcel is currently in transport to the destination area.As a API parameter this is mainly relevant for Posti internal use.
IN_DELIVERY Posti has sorted and transported the parcel to the destination, and the parcel is waiting for delivery to destination address.As a API parameter this is mainly relevant for Posti internal use.

Supported Main Products

The following is a rough outline for supported products. For actual product codes and descriptions are not listed here see http://www.posti.fi for more details.

  1. Parcel products are supported (2101 Express Morning, 2102 Business Day, 2103 Economy, 2104 Flex, 2106 Smartpost)
  2. Additional services are supported where applicable (3106 Saturday, 3121 Morning Delivery)
  3. Transport units are supported (2143 Express Morning, 2144 Business Day, 2145 Express Flex)
  4. International parcels from outside of Finland (for 2101, 2102, 2103, ..) are only supported after being sorted in Finland

The following are not supported

  1. Express City (2124) / same day products are not supported for pickup and collect schedules
  2. Express Point (2105) is dependent on agreed upon schedules with customer
  3. Not supported products include e.g. Termo (2127), customer returns (2110), courier service (2111,2112) and other products (e.g. 2116, …)
  4. Letter products (5001,5002,5003..) are not supported
  5. International parcels from Finland are not supported (EMS 2017, Priority 2015, Economy 2013)
  6. Freight (2720) are not supported