Track API Request
- 15 Aug 2024
- 5 Minutes to read
- Contributors
- Print
- DarkLight
Track API Request
- Updated on 15 Aug 2024
- 5 Minutes to read
- Contributors
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
The following details how to track a package with Mercury via an API request.
Usage Note
The Track Request API should be used to look up tracking information for individual shipments on an ad-hoc basis. Each package may be tracked once per hour (24 times per day). If you need updates for multiple shipments at once, please use the tracking file.
Overview
The protocol is based on XML data exchange with HTTP used as a transport. A non-validating parser is used and hence no internal or external DTD needs to be specified. The data must be well formed and all validation is handled at the application (not parser) level. Error handling will be done by always including the <Errors> container in the response. The Errors element will not be returned if no errors are found.
Connection
To connect to the site use the following HTTPS URL via regular POST method with the parameter RQXML=<your xml document> https://api.landmarkglobal.com/v2/Track.php
Encoding
Mercury uses UTF-8 for character encoding. If your system outputs in an encoding other than UTF-8, please include an encoding flag in your XML header.
Example: <?xml version="1.0" encoding="UTF-8"?>
Example: <?xml version="1.0" encoding="ISO-8859-1"?>
Test Mode
When first given access to the API, the client will be placed in Test mode. Requests made while in test mode will not act on live data. After approval has been received to go live from Landmark, all requests are active unless the <Test> flag is passed. During a test API call, orders will not be cancelled but errors will be reported when appropriate.
During a test API call, validation will be very basic, focusing on fields being required and passing sane values. Assuming the request passes the basic validation, responses are randomized. Some requests will succeed and some will fail with different error messages. This is done so that the programmer has an opportunity to see a wide variety of responses and can be prepared to handle many potential results.
TrackRequest
<TrackRequest>
<Login>
<Username>demoapi</Username>
<Password>demo123</Password>
</Login>
<Test>true</Test>
<ClientID>218</ClientID> <!-- Required if more than one client under user, otherwise Optional -->
<!-- Reference OR TrackingNumber OR PackageReference is required, but not all three -->
<Reference/>
<TrackingNumber>LTN123121</TrackingNumber>
<PackageReference/>
<RetrievalType>Historical</RetrievalType> <!-- Optional Node. Will return all tracking statuses for a packages if populated. Will return last tracking status if empty or node not present -->
</TrackRequest>
TrackResponse
<TrackResponse>
<Errors> <!-- Only if Error(s) occur is this element included-->
<Error>
<ErrorCode>Invalid</ErrorCode>
<ErrorMessage>No shipment found</ErrorMessage>
</Error>
</Errors>
<Result>
<Success>true</Success>
<ShipmentDetails>
<EndDeliveryCarrier>Canada Post</EndDeliveryCarrier>
</ShipmentDetails>
<Packages>
<Package>
<TrackingNumber>1Z123971A4</TrackingNumber>
<LandmarkTrackingNumber>LTN123121</LandmarkTrackingNumber>
<PackageReference/>
<Events>
<Event>
<Status>Delivered</Status>
<DateTime>2019-01-01 13:21:45</DateTime> <!-- YYYY-MM-DD HH:MM:SS 24h format in America/Chicago time per the IANA TimeZone Database https://www.iana.org/time-zones -->
<Location>Windsor, ON</Location> <!-- If available-->
<EventCode>500</EventCode> <!-- Only included if the request RetrievalType = "Historical" -->
</Event>
</Events>
</Package>
</Packages>
</Result>
</TrackResponse>
Possible tracking status codes include:
- 50 Shipment Data Uploaded
- 60 Shipment inventory allocated
- 75 Shipment Processed
- 80 Shipment Fulfilled
- 90 Shipment held for payment
- 100 Shipment information transmitted to carrier
- 125 Customs Cleared
- 135 Customs Issue
- 150 Crossing Border
- 155 Crossing Received
- 200 Item scanned at postal facility
- 225 Item grouped at Landmark or partner facility
- 250 Item scanned for crossing
- 275 Item in transit with carrier
- 300 Item out for delivery
- 400 Attempted delivery
- 410 Item available for pickup
- 450 Item re-directed to new address
- 500 Item successfully delivered
- 510 Proof Of Delivery
- 550 Return received at handling facility
- 570 Return Received
- 800 Claim Issued
- 900 Delivery failed
Note: These are general explanations of the meaning of each status code; the text of actual status updates may differ.
Possible Errors
This table lists all errors that may be returned by the Track API endpoint. [Brackets] in the ErrorMessage are used to represent to the value passed for the related element. An example is provided when an ErrorMessage is variable.
| Related Element(s) | ErrorMessage | Details/Action |
|---|---|---|
| General Errors | ||
| User, API | User [username] does not have permissions to this API | |
| Failure authenticating user | ||
| User is not available. Check your username/password | ||
| N/A | Unable to parse characters | Ensure that special characters are properly encoded and an encoding flag is included in your XML header. Example: <?xml version=""1.0"" encoding=""UTF-8""?> Example: <?xml version=""1.0"" encoding=""ISO-8859-1""?> |
| <Login> Errors | ||
| Login | Required element Login not found | Provide login credentials and verify the XML can be parsed |
| Login name not provided | ||
User, ClientID | Request is missing client ID | |
| Unable to authenticate the user credentials | ||
| Client is inactive | ||
| Client has been deactivated. Permission denied | ||
| User [username] does not have permissions to client: [clientID] | ||
| Unable to determine desired client for this user | If user has access to more than one client, the ClientID is required | |
| Username, password | The username/password combination provided is invalid | |
| The username/password combination provided is disabled | ||
| Password not provided | ||
Errors Specific to Track API | ||
| Reference | Either Reference, Package Reference or TrackingNumber is required, none were found | |
| N/A | Insufficient data provided to determine shipment. Must provide a valid reference or tracking number | |
| Could not find shipment in our system | ||
| Duplicate results found. Shipment could not be tracked | ||
| No data available for shipment | ||
For more information on tracking, please see the Tracking Overview.
Was this article helpful?