REST API - Arrival Times
1 General
1.1 Introduction
Below is a description of the interface that the Shiptrack.com service offers. All queries are made via HTTPS. The HTTP headers listed in the table below must be set with the values listed. The caller is authenticated at the interface using a previously defined username and password using the HTTP Basic Authentication Method (refer to RFC2617).
HTTP-Header | Value |
|---|---|
Content-Type | application/json |
1.3 Error handling
To ensure that the caller receives a meaningful error message when an error occurs in the interface, the interface sends a response with an HTTP status code that represents the error. In addition, a message is returned that contains detailed information about the error. For example, for the error that a customer is specified as parameter that does not exist, the HTTP status code 404 is returned. The corresponding detail error message looks like this:
{
"error": {
"code": "406",
"message": "Not all required values are available!"
}
}
Below is a table with all known Shiptrack.com specific error codes for this interface:
HTTP-Status | Description |
|---|---|
401 | Authentication error. |
403 | Interface usage was not purchased. |
404 | No eta found for provided information. |
406 | Mandatory values missing. |
Inhalt: |
2 Request
2.1 Endpoint path structure
To request an arrival time, the endpoint URL must have the following structure:
2.2 Request body
Field name | Data type | Description | Required |
|---|---|---|---|
CarrierName | String | Carrier abbreviation | X |
SenderZip | String | Sender postal code |
|
SenderIsoA2 | String | Two-digit sender country code (ISO3166) | X |
RecipientZip | String | Recipient postal code |
|
RecipientIsoA2 | String | Two-digit recipient country code (ISO3166) | X |
ServiceType | String | Service type of the carrier |
|
QualityType | String | Accuracy specification | X |
UseAdvancedSearch | String | Search in all quality types |
|
2.3 Examples
2.3.1 GET
2.3.2 POST
{
"CarrierName": "UPS",
"SenderZip": "44565",
"SenderIsoA2": "DE",
"RecipientZip": "00049",
"RecipientIsoA2": "IT",
"ServiceType": null,
"QualityType": "ZipToZip",
"UseAdvancedSearch": "True"
}
3 Response
If the call was successful, the following will be returned:
Field name | Data type | Description |
|---|---|---|
CarrierName | String | Carrier short name (see 4 Carrier Abbreviation) |
SenderZip | String | Sender postal code |
SenderIsoA2 | String | Two-digit sender country code (ISO3166) |
RecipientZip | String | Recipient postal code |
RecipientIsoA2 | String | Two-digit recipient country code (ISO3166) |
ServiceType | String | Service type of the carrier |
QualityType | String | Accuracy specification |
UseAdvancedSearch | String | Search in all quality types |
MedEtaInHours | String | Running time in hours (median) |
MedEtaTime | String | Delivery time (median) |
3.1 Possible quality types
Key | Description |
|---|---|
ZipToZipWithService | Search by CarrierName, SenderIsoA2, SenderZip, RecipientIsoA2, RecipientZip, ServiceType |
ZipToZip | Search by CarrierName, SenderIsoA2, SenderZip, RecipientIsoA2, RecipientZip |
CountryToZip | Search by CarrierName, SenderIsoA2, RecipientIsoA2, RecipientZip |
ZipToCountry | Search by CarrierName, SenderIsoA2, SenderZip, RecipientIsoA2 |
CountryToCountry | Search by CarrierName, SenderIsoA2, RecipientIsoA2 |
{
"@odata.context": "https://service.shiptrack.com/clients/00000000-0000-0000-0000-000000000000/$metadata#arrivaltimes/$entity",
"Id": "ed0c88b5-8d5d-489c-b341-79eee0c388f1",
"SenderZip": "44565",
"SenderIsoA2": "DE",
"RecipientZip": "00049",
"RecipientIsoA2": "IT",
"ServiceType": null,
"CarrierName": "UPS",
"QualityType": "ZipToZip",
"ServiceType": null,
"UseAdvancedSearch": True
"MedEtaInHours": "55",
"MedEtaTime": "09:42:00"
}
4 Carrier abbreviation
All currently known carrier abbreviations are listed below.