trackingmore-sdk-python
=================
The Python SDK of TrackingMore API
Contact: <manage@trackingmore.org>
## Official document
[Document](https://www.trackingmore.com/docs/trackingmore/d5ac362fc3cda-api-quick-start)
Supported Python Versions
=========================
- 3.6
- 3.7
- 3.8
- 3.9
- 3.10
- pypy3
## Index
1. [Installation](https://github.com/TrackingMore-API/trackingmore-sdk-python#installation)
2. [Testing](https://github.com/TrackingMore-API/trackingmore-sdk-python#testing)
3. [Error Handling](https://github.com/TrackingMore-API/trackingmore-sdk-python#error-handling)
4. SDK
1. [Couriers](https://github.com/TrackingMore-API/trackingmore-sdk-python#couriers)
2. [Trackings](https://github.com/TrackingMore-API/trackingmore-sdk-python#trackings)
3. [Air Waybill](https://github.com/TrackingMore-API/trackingmore-sdk-python#air-waybill)
## Installation
```
$ pip install trackingmore-sdk-python
```
## Via source code
Download the code archive, without unzip it, go to the
source root directory, then run:
```
$ pip install trackingmore-sdk-python.zip
```
## Quick Start
```python
import trackingmore
trackingmore.api_key = 'you api key'
try:
couriers = trackingmore.courier.get_all_couriers()
print(couriers)
except trackingmore.exception.TrackingMoreException as ce:
print(ce)
except Exception as e:
print("other error:", e)
```
## Testing
```
pytest
```
## Error handling
**Throw** by the new SDK client
```python
import trackingmore
trackingmore.api_key = ''
try:
couriers = trackingmore.courier.get_all_couriers()
print(couriers)
except trackingmore.exception.TrackingMoreException as ce:
print(ce)
# API Key is missing
```
**Throw** by the parameter validation in function
```python
import trackingmore
trackingmore.api_key = 'you api key'
try:
params = {'tracking_number': ''}
couriers = trackingmore.courier.detect(params)
print(couriers)
except trackingmore.exception.TrackingMoreException as ce:
print(ce)
# Tracking number cannot be empty
```
## Examples
## Couriers
##### Return a list of all supported couriers.
https://api.trackingmore.com/v4/couriers/all
```python
try:
result = trackingmore.courier.get_all_couriers()
print(result)
except trackingmore.exception.TrackingMoreException as ce:
print(ce)
except Exception as e:
print("other error:", e)
```
##### Return a list of matched couriers based on submitted tracking number.
https://api.trackingmore.com/v4/couriers/detect
```python
params = {'tracking_number': '92612903029511573030094547'}
try:
result = trackingmore.courier.detect(params)
print(result)
except trackingmore.exception.TrackingMoreException as ce:
print(ce)
except Exception as e:
print("other error:", e)
```
## Trackings
##### Create a tracking.
https://api.trackingmore.com/v4/trackings/create
```python
try:
params = {'tracking_number': '92612903029511573030094547','courier_code':'usps'}
result = trackingmore.tracking.create_tracking(params)
print(result)
except trackingmore.exception.TrackingMoreException as ce:
print(ce)
except Exception as e:
print("other error:", e)
```
##### Get tracking results of multiple trackings.
https://api.trackingmore.com/v4/trackings/get
```python
try:
# Perform queries based on various conditions
# params = {'tracking_numbers': '92612903029511573030094547', 'courier_code': 'usps'}
# params = {'tracking_numbers': '92612903029511573030094547,92612903029511573030094548', 'courier_code': 'usps'}
params = {'created_date_min': '2023-08-23T14:00:00+08:00', 'created_date_max': '2023-08-23T15:04:00+08:00'}
result = trackingmore.tracking.get_tracking_results(params)
print(result)
except trackingmore.exception.TrackingMoreException as ce:
print(ce)
except Exception as e:
print("other error:", e)
```
##### Create multiple trackings (Max. 40 tracking numbers create in one call).
https://api.trackingmore.com/v4/trackings/batch
```python
try:
params = [{'tracking_number': '92612903029511573030094593', 'courier_code': 'usps'},
{'tracking_number': '92612903029511573030094594', 'courier_code': 'usps'}]
result = trackingmore.tracking.batch_create_trackings(params)
print(result)
except trackingmore.exception.TrackingMoreException as ce:
print(ce)
except Exception as e:
print("other error:", e)
```
##### Update a tracking by ID.
https://api.trackingmore.com/v4/trackings/update/{id}
```python
params = {'customer_name': 'New name', 'note': 'New tests order note'}
id_string = "9a2f732e29b5ed2071d4cf6b5f4a3d19"
try:
result = trackingmore.tracking.update_tracking_by_id(id_string, params)
print(result)
except trackingmore.exception.TrackingMoreException as ce:
print(ce)
except Exception as e:
print("other error:", e)
```
##### Delete a tracking by ID.
https://api.trackingmore.com/v4/trackings/delete/{id}
```python
id_string = "9a2f7d1e8b912b729388c5835c188c28"
try:
result = trackingmore.tracking.batch_create_trackings(params)
print(result)
except trackingmore.exception.TrackingMoreException as ce:
print(ce)
except Exception as e:
print("other error:", e)
```
##### Retrack expired tracking by ID.
https://api.trackingmore.com/v4/trackings/retrack/{id}
```python
id_string = "9a2f7d1e8b912b729388c5835c188c28"
try:
result = trackingmore.tracking.retrack_tracking_by_id(id_string)
print(result)
except trackingmore.exception.TrackingMoreException as ce:
print(ce)
except Exception as e:
print("other error:", e)
```
## Air Waybill
##### Create an air waybill.
https://api.trackingmore.com/v4/awb
```python
params = {'awb_number': '235-69030430'}
try:
result = trackingmore.air_waybill.create_an_air_waybill(params)
print(result)
except trackingmore.exception.TrackingMoreException as ce:
print(ce)
except Exception as e:
print("other error:", e)
```
## Response Code
Trackingmore uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a charge failed, etc.), and codes in the 5xx range indicate an TrackingMore's server error.
Http CODE|META CODE|TYPE | MESSAGE
----|-----|--------------|-------------------------------
200 |200 | <code>Success</code> | Request response is successful
400 |400 | <code>BadRequest</code> | Request type error. Please check the API documentation for the request type of this API.
400 |4101 | <code>BadRequest</code> | Tracking No. already exists.
400 |4102 | <code>BadRequest</code> | Tracking No. no exists. Please use 「Create a tracking」 API first to create shipment.
400 |4103 | <code>BadRequest</code> | You have exceeded the shipment quantity of API call. The maximum quantity is 40 shipments per call.
400 |4110 | <code>BadRequest</code> | The value of tracking_number is invalid.
400 |4111 | <code>BadRequest</code> | Tracking_number is required.
400 |4112 | <code>BadRequest</code> | Invalid Tracking ID.
400 |4113 | <code>BadRequest</code> | Retrack is not allowed. You can only retrack an expired tracking.
400 |4120 | <code>BadRequest</code> | The value of courier_code is invalid.
400 |4121 | <code>BadRequest</code> | Cannot detect courier.
400 |4122 | <code>BadRequest</code> | Missing or invalid value of the special required fields for this courier.
400 |4130 | <code>BadRequest</code> | The format of Field name is invalid.
400 |4160 | <code>BadRequest</code> | The awb_number is required or invaild format.
400 |4161 | <code>BadRequest</code> | The awb airline does not support yet.
400 |4190 | <code>BadRequest</code> | You are reaching the maximum quota limitation, please upgrade your current plan.
401 |401 | <code>Unauthorized</code> | Authentication failed or has no permission. Please check and ensure your API Key is correct.
403 |403 | <code>Forbidden</code> | Access prohibited. The request has been refused or access is not allowed.
404 |404 | <code>NotFound</code> | Page does not exist. Please check and ensure your link is correct.
429 |429 | <code>TooManyRequests</code>| Exceeded API request limits, please try again later. Please check the API documentation for the limit of this API.
500 |511 | <code>ServerError</code> | Server error. Please contact us: service@trackingmore.org.
500 |512 | <code>ServerError</code> | Server error. Please contact us: service@trackingmore.org.
500 |513 | <code>ServerError</code> | Server error. Please contact us: service@trackingmore.org.
Raw data
{
"_id": null,
"home_page": "https://www.trackingmore.com/docs/trackingmore/d5ac362fc3cda-api-quick-start",
"name": "trackingmore-sdk-python",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "trackingmore,api,tracking",
"author": "TrackingMore",
"author_email": "manage@trackingmore.org",
"download_url": "https://files.pythonhosted.org/packages/85/12/4fe03ef9b02b612e885deb4908cda949511c420d984b9f08f492ebdbb5e0/trackingmore_sdk_python-0.1.4.tar.gz",
"platform": null,
"description": "trackingmore-sdk-python\n=================\n\nThe Python SDK of TrackingMore API\n\nContact: <manage@trackingmore.org>\n\n## Official document\n\n[Document](https://www.trackingmore.com/docs/trackingmore/d5ac362fc3cda-api-quick-start)\n\nSupported Python Versions\n=========================\n\n- 3.6\n- 3.7\n- 3.8\n- 3.9\n- 3.10\n- pypy3\n\n## Index\n1. [Installation](https://github.com/TrackingMore-API/trackingmore-sdk-python#installation)\n2. [Testing](https://github.com/TrackingMore-API/trackingmore-sdk-python#testing)\n3. [Error Handling](https://github.com/TrackingMore-API/trackingmore-sdk-python#error-handling)\n4. SDK\n 1. [Couriers](https://github.com/TrackingMore-API/trackingmore-sdk-python#couriers)\n 2. [Trackings](https://github.com/TrackingMore-API/trackingmore-sdk-python#trackings)\n 3. [Air Waybill](https://github.com/TrackingMore-API/trackingmore-sdk-python#air-waybill)\n\n\n## Installation\n\n```\n$ pip install trackingmore-sdk-python\n```\n\n## Via source code\n\nDownload the code archive, without unzip it, go to the\nsource root directory, then run:\n\n```\n$ pip install trackingmore-sdk-python.zip\n```\n\n## Quick Start\n\n```python\nimport trackingmore\n\ntrackingmore.api_key = 'you api key'\n\ntry:\n couriers = trackingmore.courier.get_all_couriers()\n print(couriers)\nexcept trackingmore.exception.TrackingMoreException as ce:\n print(ce)\nexcept Exception as e:\n print(\"other error:\", e)\n\n```\n\n## Testing\n```\npytest\n```\n\n## Error handling\n\n**Throw** by the new SDK client\n\n```python\nimport trackingmore\n\ntrackingmore.api_key = ''\n\ntry:\n couriers = trackingmore.courier.get_all_couriers()\n print(couriers)\nexcept trackingmore.exception.TrackingMoreException as ce:\n print(ce)\n\n# API Key is missing\n```\n\n**Throw** by the parameter validation in function\n\n```python\nimport trackingmore\n\ntrackingmore.api_key = 'you api key'\n\ntry:\n params = {'tracking_number': ''}\n couriers = trackingmore.courier.detect(params)\n print(couriers)\nexcept trackingmore.exception.TrackingMoreException as ce:\n print(ce) \n\n# Tracking number cannot be empty\n```\n## Examples\n\n## Couriers\n##### Return a list of all supported couriers.\nhttps://api.trackingmore.com/v4/couriers/all\n```python\ntry:\n result = trackingmore.courier.get_all_couriers()\n print(result)\nexcept trackingmore.exception.TrackingMoreException as ce:\n print(ce)\nexcept Exception as e:\n print(\"other error:\", e) \n\n```\n\n##### Return a list of matched couriers based on submitted tracking number.\nhttps://api.trackingmore.com/v4/couriers/detect\n```python\nparams = {'tracking_number': '92612903029511573030094547'}\ntry:\n result = trackingmore.courier.detect(params)\n print(result)\nexcept trackingmore.exception.TrackingMoreException as ce:\n print(ce)\nexcept Exception as e:\n print(\"other error:\", e) \n```\n\n## Trackings\n##### Create a tracking.\nhttps://api.trackingmore.com/v4/trackings/create\n```python\ntry:\n params = {'tracking_number': '92612903029511573030094547','courier_code':'usps'}\n result = trackingmore.tracking.create_tracking(params)\n print(result)\nexcept trackingmore.exception.TrackingMoreException as ce:\n print(ce)\nexcept Exception as e:\n print(\"other error:\", e) \n```\n\n##### Get tracking results of multiple trackings.\nhttps://api.trackingmore.com/v4/trackings/get\n```python\ntry:\n # Perform queries based on various conditions\n # params = {'tracking_numbers': '92612903029511573030094547', 'courier_code': 'usps'}\n # params = {'tracking_numbers': '92612903029511573030094547,92612903029511573030094548', 'courier_code': 'usps'}\n params = {'created_date_min': '2023-08-23T14:00:00+08:00', 'created_date_max': '2023-08-23T15:04:00+08:00'}\n result = trackingmore.tracking.get_tracking_results(params)\n print(result)\nexcept trackingmore.exception.TrackingMoreException as ce:\n print(ce)\nexcept Exception as e:\n print(\"other error:\", e) \n```\n\n##### Create multiple trackings (Max. 40 tracking numbers create in one call).\nhttps://api.trackingmore.com/v4/trackings/batch\n```python\ntry:\n params = [{'tracking_number': '92612903029511573030094593', 'courier_code': 'usps'},\n {'tracking_number': '92612903029511573030094594', 'courier_code': 'usps'}]\n result = trackingmore.tracking.batch_create_trackings(params)\n print(result)\nexcept trackingmore.exception.TrackingMoreException as ce:\n print(ce)\nexcept Exception as e:\n print(\"other error:\", e) \n```\n\n##### Update a tracking by ID.\nhttps://api.trackingmore.com/v4/trackings/update/{id}\n```python\nparams = {'customer_name': 'New name', 'note': 'New tests order note'}\nid_string = \"9a2f732e29b5ed2071d4cf6b5f4a3d19\"\ntry:\n result = trackingmore.tracking.update_tracking_by_id(id_string, params)\n print(result)\nexcept trackingmore.exception.TrackingMoreException as ce:\n print(ce)\nexcept Exception as e:\n print(\"other error:\", e) \n```\n\n##### Delete a tracking by ID.\nhttps://api.trackingmore.com/v4/trackings/delete/{id}\n```python\nid_string = \"9a2f7d1e8b912b729388c5835c188c28\"\ntry:\n result = trackingmore.tracking.batch_create_trackings(params)\n print(result)\nexcept trackingmore.exception.TrackingMoreException as ce:\n print(ce)\nexcept Exception as e:\n print(\"other error:\", e) \n```\n\n##### Retrack expired tracking by ID.\nhttps://api.trackingmore.com/v4/trackings/retrack/{id}\n```python\nid_string = \"9a2f7d1e8b912b729388c5835c188c28\"\ntry:\n result = trackingmore.tracking.retrack_tracking_by_id(id_string)\n print(result)\nexcept trackingmore.exception.TrackingMoreException as ce:\n print(ce)\nexcept Exception as e:\n print(\"other error:\", e) \n```\n## Air Waybill\n##### Create an air waybill.\nhttps://api.trackingmore.com/v4/awb\n```python\nparams = {'awb_number': '235-69030430'}\ntry:\n result = trackingmore.air_waybill.create_an_air_waybill(params)\n print(result)\nexcept trackingmore.exception.TrackingMoreException as ce:\n print(ce)\nexcept Exception as e:\n print(\"other error:\", e) \n```\n\n## Response Code\n\nTrackingmore uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a charge failed, etc.), and codes in the 5xx range indicate an TrackingMore's server error.\n\n\nHttp CODE|META CODE|TYPE | MESSAGE\n----|-----|--------------|-------------------------------\n200 |200 | <code>Success</code> | Request response is successful\n400 |400 | <code>BadRequest</code> | Request type error. Please check the API documentation for the request type of this API.\n400 |4101 | <code>BadRequest</code> | Tracking No. already exists.\n400 |4102 | <code>BadRequest</code> | Tracking No. no exists. Please use \u300cCreate a tracking\u300d API first to create shipment.\n400 |4103 | <code>BadRequest</code> | You have exceeded the shipment quantity of API call. The maximum quantity is 40 shipments per call.\n400 |4110 | <code>BadRequest</code> | The value of tracking_number is invalid.\n400 |4111 | <code>BadRequest</code> | Tracking_number is required.\n400 |4112 | <code>BadRequest</code> | Invalid Tracking ID.\n400 |4113 | <code>BadRequest</code> | Retrack is not allowed. You can only retrack an expired tracking.\n400 |4120 | <code>BadRequest</code> | The value of courier_code is invalid.\n400 |4121 | <code>BadRequest</code> | Cannot detect courier.\n400 |4122 | <code>BadRequest</code> | Missing or invalid value of the special required fields for this courier.\n400 |4130 | <code>BadRequest</code> | The format of Field name is invalid.\n400 |4160 | <code>BadRequest</code> | The awb_number is required or invaild format.\n400 |4161 | <code>BadRequest</code> | The awb airline does not support yet.\n400 |4190 | <code>BadRequest</code> | You are reaching the maximum quota limitation, please upgrade your current plan.\n401 |401 | <code>Unauthorized</code> | Authentication failed or has no permission. Please check and ensure your API Key is correct.\n403 |403 | <code>Forbidden</code> | Access prohibited. The request has been refused or access is not allowed.\n404 |404 | <code>NotFound</code> | Page does not exist. Please check and ensure your link is correct.\n429 |429 | <code>TooManyRequests</code>| Exceeded API request limits, please try again later. Please check the API documentation for the limit of this API.\n500 |511 | <code>ServerError</code> | Server error. Please contact us: service@trackingmore.org.\n500 |512 | <code>ServerError</code> | Server error. Please contact us: service@trackingmore.org.\n500 |513 | <code>ServerError</code> | Server error. Please contact us: service@trackingmore.org.",
"bugtrack_url": null,
"license": "",
"summary": "The Python SDK of Trackingmore API",
"version": "0.1.4",
"project_urls": {
"Documentation": "https://github.com/TrackingMore-API/trackingmore-sdk-python",
"Homepage": "https://www.trackingmore.com/docs/trackingmore/d5ac362fc3cda-api-quick-start",
"Repository": "https://github.com/TrackingMore-API/trackingmore-sdk-python"
},
"split_keywords": [
"trackingmore",
"api",
"tracking"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ac3f7a85f64756e44a9a4321a390cdf39e62a293b91029883155de7875fc237f",
"md5": "db11dbab2a7f62e9a3c46bd78104ef64",
"sha256": "980750595763934da77f9fd91d634ba3e906ee670a9a2f5e90c8b73a59f388b7"
},
"downloads": -1,
"filename": "trackingmore_sdk_python-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "db11dbab2a7f62e9a3c46bd78104ef64",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 11280,
"upload_time": "2023-11-21T03:35:26",
"upload_time_iso_8601": "2023-11-21T03:35:26.474928Z",
"url": "https://files.pythonhosted.org/packages/ac/3f/7a85f64756e44a9a4321a390cdf39e62a293b91029883155de7875fc237f/trackingmore_sdk_python-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "85124fe03ef9b02b612e885deb4908cda949511c420d984b9f08f492ebdbb5e0",
"md5": "15b0681c5b20b23d9e4cf9a28707d404",
"sha256": "d9d03c0d1a2d931cd3ba28ef0a03853a8b39b58e2646dbc719dfaca160d0a394"
},
"downloads": -1,
"filename": "trackingmore_sdk_python-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "15b0681c5b20b23d9e4cf9a28707d404",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 7662,
"upload_time": "2023-11-21T03:35:28",
"upload_time_iso_8601": "2023-11-21T03:35:28.094005Z",
"url": "https://files.pythonhosted.org/packages/85/12/4fe03ef9b02b612e885deb4908cda949511c420d984b9f08f492ebdbb5e0/trackingmore_sdk_python-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-21 03:35:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TrackingMore-API",
"github_project": "trackingmore-sdk-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "trackingmore-sdk-python"
}
JSON
