Tracking deliveries via external API

Tracking deliveries via an external API allows businesses to integrate their shipment tracking systems with third-party services, enabling real-time updates on delivery status. This helps both businesses and customers stay informed about the current state of their shipments, improving customer satisfaction and operational efficiency.

External APIs are provided by delivery carriers like FedEx, UPS, DHL, or third-party logistics providers, which allow integration with their tracking systems to retrieve up-to-date delivery information.

Here’s a step-by-step guide on how to implement delivery tracking using an external API.

Step-by-Step Guide to Tracking Deliveries via External API

1. Identify the API Provider

The first step is to identify the API provider that will give you the necessary shipment tracking information. Common providers include:

Carrier APIs: These are provided directly by logistics companies (e.g., UPS, FedEx, DHL).
Third-Party APIs: These aggregate data from multiple carriers. Examples include AfterShip and ShipEngine.

For this guide, let’s assume you are using the UPS API for tracking delivery.

2. Obtain API Access

To use the external API for tracking, you’ll need to sign up with the service provider (e.g., UPS) and obtain an API key. This typically involves:

Creating an account with the provider.
Requesting API access through the developer portal.
Receiving an API key (authentication token) to be used in the API requests.

For example, to use the UPS Tracking API, you’ll need to:

Go to the UPS Developer Kit and register for an account.
After registration, you can access the API documentation and obtain your access credentials, including the Access Key, Username, and Password.

3. Set Up API Integration

Once you have your API access, you can begin integrating the tracking functionality into your application. This can typically be done through HTTP requests, either through REST APIs or SOAP APIs, depending on the carrier.

Example 1: Using a REST API (UPS Tracking)

For this example, let’s assume you are integrating with the UPS REST API to track a package by its tracking number.

API Endpoint: The endpoint for tracking is typically in the form: https://onlinetools.ups.com/rest/Track
API Request: Make a POST request with a JSON payload containing the tracking number.

Example in Python using the requests library:

import requests
import json

url = "https://onlinetools.ups.com/rest/Track"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_KEY"
}

payload = {
    "TrackingNumber": "1Z9999W99999999999"
}

response = requests.post(url, headers=headers, data=json.dumps(payload))

if response.status_code == 200:
    tracking_data = response.json()
    print(tracking_data)
else:
    print(f"Error: {response.status_code}")

In this code:

Replace YOUR_ACCESS_KEY with the actual API key.
TrackingNumber represents the tracking number of the package you wish to track.

This sends a request to UPS’s tracking API and returns a JSON response with tracking information, such as the current status of the shipment, estimated delivery date, and shipment history.

4. Parse and Handle the Response

Once you receive the tracking data from the external API, you’ll need to parse and display it appropriately. The response typically contains multiple fields, such as:

Tracking Status: Whether the package is in transit, delivered, or delayed.
Event Details: A list of events that occurred during the delivery process (e.g., package picked up, out for delivery, delivered).
Estimated Delivery Date: The expected date for delivery.
Delivery Location: The address or area where the package was delivered.

Example response from the UPS API:

{
    "trackResponse": {
        "shipment": {
            "shipmentStatus": "Delivered",
            "deliveryDate": "2025-04-16",
            "trackingEvents": [
                {
                    "eventDescription": "Delivered",
                    "eventDate": "2025-04-16",
                    "eventLocation": "Customer's Front Door"
                },
                {
                    "eventDescription": "Out for Delivery",
                    "eventDate": "2025-04-16",
                    "eventLocation": "UPS Facility, City, Country"
                }
            ]
        }
    }
}

Parse this data to extract meaningful information such as the current status, location, and timestamps.

5. Display Tracking Information on Your Portal

The next step is to display the tracking information on your portal or app. You can create a Tracking Page where users can input their tracking number and view live updates on their shipment’s status.

Example HTML for a Tracking Page:

<html>
<head>
    <title>Track Your Shipment</title>
</head>
<body>
    <h1>Track Your Package</h1>
    <form action="track_shipment" method="post">
        <label for="trackingNumber">Enter Tracking Number:</label>
        <input type="text" id="trackingNumber" name="trackingNumber" required>
        <button type="submit">Track</button>
    </form>
    <div id="trackingInfo">
        <!-- Display tracking information here -->
    </div>
</body>
</html>

You can display the tracking status and events dynamically by populating the HTML with the parsed data from the API response.

6. Error Handling and Monitoring

When integrating with external APIs, it’s essential to account for potential errors such as:

Invalid Tracking Numbers: Handle cases where the tracking number is not found or is invalid.
API Rate Limits: Ensure you respect the API’s rate limits, preventing excessive requests that might lead to throttling or banning.
API Downtime: Have fallback strategies, such as retry mechanisms or cached data, in case the external API becomes temporarily unavailable.

You should also include error handling in your code to ensure that users receive meaningful messages if something goes wrong.

Example of error handling in Python:

if response.status_code != 200:
    print(f"Error: Unable to retrieve tracking information. Status code: {response.status_code}")
    # You can also log the error and attempt retries if necessary

Best Practices for Tracking Deliveries via External APIs

Secure API Keys: Never expose API keys in client-side code. Use environment variables or a server-side backend to securely store your keys.
Cache Responses: To reduce the load on the API, consider caching responses for common tracking numbers to improve performance.
Provide Notifications: Enhance the user experience by offering notifications (e.g., email or SMS) when the delivery status changes.
User-Friendly Display: Ensure that the tracking information is presented in a clear and easy-to-understand manner, especially for users who are not familiar with shipping terminology.
Real-Time Updates: If your API allows it, set up a webhook to receive real-time delivery updates rather than polling the API for each status change.