marcoesposito1988/trackingmore-python

Python wrapper for the TrackingMore API

pytrackingmore

Python wrapper for the TrackingMore API

This library supports the following methods of the TrackingMore API:

• Creating a new tracking item, given the courier code and the tracking number
• Creating a batch of tracking items, given the courier code and the tracking number
• Updating a tracking item, given the courier code and the tracking number
• Deleting a tracking item, given the courier code and the tracking number
• Querying the tracking data for an item from the courier API in real time
• Detecting the courier from the tracking number

Installation

pip install trackingmore

Setup

You need a TrackingMore account in order to use the API. You can then generate an API token, which you will need to pass to the trackingmore module.

You can just do it once somewhere in the program, before using the API.

import trackingmore

trackingmore.set_api_key('my-api-key')

Creating tracking items

Before accessing information about a shipment, you must create a tracking item in TrackingMore's system. It will then be also visible in the dashboard.

Creating a single tracking item

Each shipment is identifiable through its courier code and tracking number.

>>> td = trackingmore.create_tracking_data('poste-italiane', '1234567890')
>>> trackingmore.create_tracking_item(td)

{
    "id": "b6321d71ad627cbf8c141ccc25fc659f",
    "tracking_number": "1234567890",
    "carrier_code": "poste-italiane",
    "status": "pending",
    "created_at": "2017-05-20T17:39:21+08:00",
    "customer_email": "null",
    "customer_name": "null",
    "order_id": "null",
    "title": null
}

However, while creating a tracking item, it is possible to provide additional metadata to be stored in TrackingMore's database, to facilitate your own operations. The trackingmore module includes a helper function to create a TrackingData object.

>>> td = trackingmore.create_tracking_data(
        carrier_code='poste-italiane', 
        tracking_number='0987654321', 
        title='my_first_package', 
        customer_name='Marco Esposito',
        customer_email='[email protected]', 
        order_id='my_order_id', 
        lang='it'
    )
    
>>> trackingmore.create_tracking_item(td)

{
    "id": "b6321d71ad627cbf8c141ccc25fc6600",
    "tracking_number": "0987654321",
    "carrier_code": "poste-italiane",
    "status": "pending",
    "created_at": "2017-05-20T17:39:23+08:00",
    "customer_email": "[email protected]",
    "customer_name": "Marco Esposito",
    "order_id": "my_order_id",
    "title": "my_first_package"
}

Batch creation

It is possible to create multiple tracking items with a single API call.

>>> tds = [
        trackingmore.create_tracking_data('poste-italiane', '1234567890'),
        trackingmore.create_tracking_data('dhl', 'abc123456')
    ]
    
>>> trackingmore.create_tracking_items_batch(tds)
[
    {
        "id": "b6321d71ad627cbf8c141ccc25fc6601",
        "tracking_number": "1234567890",
        "carrier_code": "poste-italiane",
        "status": "pending",
        "created_at": "2017-05-20T17:39:26+08:00",
        "customer_email": "null",
        "customer_name": "null",
        "order_id": "null",
        "title": null
    },
    {
        "id": "b6321d71ad627cbf8c141ccc25fc6602",
        "tracking_number": "abc123456",
        "carrier_code": "dhl",
        "status": "pending",
        "created_at": "2017-05-20T17:39:26+08:00",
        "customer_email": "null",
        "customer_name": "null",
        "order_id": "null",
        "title": null
    }
]

Updating tracking items

It is also possible to update the tracking item metadata after creation.

>>> td = trackingmore.create_tracking_data(
        carrier_code='poste-italiane', 
        tracking_number='1234567890', 
        customer_name='Marco Esposito',
        customer_email='[email protected]'
    )
    
>>> trackingmore.update_tracking_item(td)
{
    "id": "b6321d71ad627cbf8c141ccc25fc659f",
    "tracking_number": "1234567890",
    "carrier_code": "poste-italiane",
    "status": "pending",
    "created_at": "2017-05-20T17:39:21+08:00",
    "customer_email": "[email protected]",
    "customer_name": "Marco Esposito",
    "order_id": "null",
    "title": null
}

Fetching information about tracking items

Once a tracking item has been created, it will synchronize periodically (every few hours) with the courier's system.

Normal query

It is possible to fetch the latest information from the TrackingMore servers by providing the courier code and tracking number.

>>> trackingmore.get_tracking_item('ups', '1Z97X17XYW06605211')
{
    "id": "ac9326a212b9b8660759f55bac89df2b",
    "tracking_number": "1Z97X17XYW06605211",
    "carrier_code": "ups",
    "status": "transit",
    "created_at": "2015-11-20T21:01:30+08:00",
    "updated_at": "2015-11-21T15:27:26+08:00",
    "original_country": "United States",
    "itemTimeLength": null,
    "origin_info": {
        "weblink": "http:\/\/www.ups.com\/content\/us\/en\/contact\/index.html?WT.svl=Footer",
        "phone": null,
        "carrier_code": "ups",
        "trackinfo": [{
            "Date": "2015-11-06 09:46:00",
            "StatusDescription": "package transferred to post office.",
            "Details": ""
        }, {
            "Date": "2015-11-06 05:41:00",
            "StatusDescription": "destination scan",
            "Details": "US,BALDWIN PARK"
        }, 
        ...
        ]
    }
}

Realtime query

This method forces the TrackingMore server to fetch the latest information available from the courier's system. A rate limit applies.

>>> td = trackingmore.create_tracking_data('china-ems', 'LK664578623CN')
    
>>> trackingmore.realtime_tracking(td)

{
    "items": [{
        "id": "442f798ea35749e7605d1a73d4181a01",
        "tracking_number": "RE113184005HK",
        "carrier_code": "hong-kong-post",
        "status": "transit",
        "original_country": "Hong Kong [CN]",
        "destination_country": "Colombia",
        "itemTimeLength": null,
        "origin_info": {
            "weblink": "http:\/\/www.hongkongpost.hk\/",
            "phone": "852 2921 2222",
            "carrier_code": "hong-kong-post",
            "trackinfo": [{
                "Details": "CO",
                "StatusDescription": "The item ( RE113184005HK ) left Hong Kong for its destination on  10-Oct-2015 ",
                "Date": "2015-10-09 00:00"
            }]
        },
        "destination_info": {
            "weblink": "http:\/\/www.4-72.com.co\/",
            "phone": "(57-1) 4722000",
            "carrier_code": "colombia-post",
            "trackinfo": [{
                "Date": "2015-10-22 20:52",
                "StatusDescription": "DIGITALIZADO",
                "Details": "CTP.CENTRO A"
            }, {
                "Date": "2015-10-22 17:02",
                "StatusDescription": "Registro de entrega exitosa",
                "Details": ""
            }, {
                "Date": "2015-10-22 16:55",
                "StatusDescription": "ENTREGADO",
                "Details": "CD.MONTEVIDEO"
            },
            ...
            ]
        }
    "lastEvent": "DIGITALIZADO,CTP.CENTRO A,2015-10-22 20:52",
    "lastUpdateTime": "2015-10-22 20:52"
    }]
}

Deleting a tracking item

It is possible to delete a tracking item when it is not needed any more. It can be added again later at no additional cost (TrackingMore charges per package).

>>> trackingmore.delete_tracking_item('ups', '1Z97X17XYW06605211')
[]

Notes

The author is not affiliated to TrackingMore. Every responsibility is declined.