Application Programming Interface (API)

at EC-Ship System
for System Integration on HKPost Mail Tracking

Version: 1.0

Last Updated : 11 April 2024

© The Government of the Hong Kong Special Administrative Region

The contents of this document remain the property of and may not be reproduced in whole or
in part without the expressed permission of the Government of HKSAR
Application Programming Interface (API) at EC-Ship System for System Integration on HKPost Mail Tracking
________________________________________________________________________________________________________

Amendment History
Version Amendment Description Author /
Date Updated By
1.0 April 2024 Release Version CW Lai

Version 1.0 Page 1 of 7

Application Programming Interface (API) at EC-Ship System for System Integration on HKPost Mail Tracking
________________________________________________________________________________________________________

Table of Contents
1. HKPost Mail Tracking Web Services URL ...................................................................................................... 3
2. HKPost Mail Tracking Web Services Authentication ....................................................................................... 4
3. HKPost Mail Tracking API – Track and Trace mail item delivery status ......................................................... 5
4. Appendix A – Status Code and Error Message ................................................................................................. 7

Version 1.0 Page 2 of 7

Application Programming Interface (API) at EC-Ship System for System Integration on HKPost Mail Tracking
________________________________________________________________________________________________________

1. HKPost Mail Tracking Web Services URL

The Hongkong Post Mail Tracking API service is provided by the EC-Ship API platform, the production
URL is shown as follow:

Production Site URL: https://partner.hongkongpost.hk/mailTrackingAPI/

Note1: Request limit per day: 100,000 (Please contact Hong Kong Post if special arrangement is required)
Note2: The frequency of request: 100ms, system will refuse the request if frequency of request exceed the
limit. Please group the tracking item into one request as possible.

2. EC-Ship Web Services Overview

API Doc URL: https://partner.hongkongpost.hk/mailTrackingAPI/swagger-ui/index.html

Web Services Operations Usage

Tracking POST /api/version/1/mailTracking Retrieve item tracking details
Common POST /api/authenticate Get token for access

Version 1.0 Page 3 of 7

Application Programming Interface (API) at EC-Ship System for System Integration on HKPost Mail Tracking
________________________________________________________________________________________________________

3. HKPost Mail Tracking Web Services Authentication

Authentication key is required to call EC-Ship API. The credential is provided registered EC-Ship API users.
Token must be get from authentication API, and included in your request Header as specified in EC-Ship API.
Without this information, your API request will be rejected.

Example

Credential information is included in Header as follows:

1. User should get token as follow; the token is valid for 15 minutes.
POST /api/authenticate

Request

Parameter Data Type Length Mandatory Remark

Constraint
(byte)
sysId String 20 Y API Username
sysSecret String 36 Y Access Key

Response

Parameter Data Type Description

id_token String Token of access API
expiry Integer Unix timestamps in seconds

2. Access API with Bearer HTTP authentication as described at w3.org.

i.e. Authorization: Bearer <id_token returned>

Version 1.0 Page 4 of 7

Application Programming Interface (API) at EC-Ship System for System Integration on HKPost Mail Tracking
________________________________________________________________________________________________________

4. HKPost Mail Tracking API – Track and Trace mail item delivery status

User should call this request to send the item numbers (also known as tracking numbers) to
Hongkong Post system. The system will return the mail items’ delivery status

POST /api/version/1/mailTracking

Request
Parameter Data Type Length Mandatory Remark
Constraint

(byte)
lang String 1 Y Language code
A' - English, Traditional Chinese and
Simplified Chinese message will be
returned

'E' - Only English message will be

returned

'C' - Only Traditional Chinese

message will be returned

'S' - Only Simplified Chinese

message will be returned

In case language code “E”, “C”, “S”

is received, values of other languages
will be returned as empty value.
An array of Item No (max 30 items)
itemNo String 13 Y Mail item tracking number
(E.g. RB000000010HK)

Version 1.0 Page 5 of 7

Application Programming Interface (API) at EC-Ship System for System Integration on HKPost Mail Tracking
________________________________________________________________________________________________________

Response
Parameter Data Type Description Example
status Number Reference to Appendix A 0
errMsg String Error message
itemCount Number No. of message returned 30
An array of Delivery Result (max 30 items)
deliveryResultList
itemNo String Mail item tracking number RB000000010HK
status Number Reference to Appendix A 0
errMsg String Error message
postingDateTime String The posting date and time of the item in 27-02-2017 16:00
DD-MM-YYYY HH24:MI
dropOffPoint_e String Drop-off Point in English Queen's Road
Post Office
dropOffPoint_c String Drop-off Point in Traditional Chinese 皇后大道郵政局
dropOffPoint_s String Drop-off Point in Simplified Chinese 皇后大道邮政局
orgCnty_code String Original country code HK
Reference to Appendix B
orgCnty_e String Original in English HONG KONG
orgCnty_c String Original in Traditional Chinese 香港
orgCnty_s String Original in Simplified Chinese 香港
destCnty_code String Destination country code HK
Reference to Appendix B
destCnty_e String Destination in English HONG KONG
destCnty_c String Destination in Traditional Chinese 香港
destCnty_s String Destination in Simplified Chinese 香港
milestone_e String Milestone description in English Delivered
milestone_c String Milestone description in Traditional 已成功派遞
Chinese
milestone_s String Milestone description in Simplified Chinese 已成功派递
Event Detail (A list of event history)
itemDeliveryStatusDetailList
eventDateTime String The event date and time (In the time zone 01-03-2017 11:00
of the location) in DD-MM-YYYY
HH24:MI
eventLocation_code String The location country code HK
eventLocation_e String The location of the event in English HONG KONG
eventLocation_c String The location of the event in Traditional 香港
Chinese
eventLocation_s String The location of the event in Simplified 香港
Chinese
eventMsg_e String The message of the event in English Delivered
eventMsg_c String The message of the event in Traditional 成功派遞
Chinese
eventMsg_s String The message of the event in Simplified 成功派递
Chinese

Version 1.0 Page 6 of 7

Application Programming Interface (API) at EC-Ship System for System Integration on HKPost Mail Tracking
________________________________________________________________________________________________________

5. Appendix A – Status Code and Error Message

Status Code Meaning

0 Success
1001 item number does not exist
1002 Invalid item number format
1003 Tracking period has been expired
1004 Item no not allowed to enquiry
9991 Exceed API request frequency
9992 Invalid Credential
9993 Invalid API format
9994 Exceed API request limit
9995 Exceed the max. enquiry items
9996 Invalid Language
9997 Empty item number array
9998 Invalid input
9999 Service temporary unavailable

Version 1.0 Page 7 of 7