Quick start
Use cURL to get started with Vizion's Container Tracking API
This tutorial will walk through how to use the Container Tracking API to subscribe to a container and receive location updates. You will make use of the command line and cURL to access the API, which is a language option in Vizion API reference.
Getting started
You will need a few items before getting started:
- Your Vizion API key
- The container ID and carrier code of a shipment you want to track
- Access to the command line on your computer
Create a callback URL
The Container Tracking API is designed to provide realtime data updates to you through webhooks, eliminating the need to manually check for changes at regular intervals. Vizion will send these updates directly to the callback URL you provide.
Polling method
If your use case is better suited for a polling method, you have the option to exclude the callback URL when subscribing to a container. Instead, you can utilize a GET request for List Reference Updates, which will retrieve a list of Update Payloads specific to the provided reference ID.
To demonstrate the functionality of the Vizion API first before pointing to a URL on your server, you can use Webhook.site to create a temporary endpoint to use as your callback URL. Go to webhook.site and copy the unique URL generated for you.
 unique URL](https://files.readme.io/a5dd5d0-Screen_Shot_2023-11-27_at_5.10.03_PM.png)
Make an API request to create a reference
For this tutorial, Create reference via Carrier Code will be used. You can explore other input options by referring to the Input options for tracking containers guide.
- Using the cURL request below, replace
callback_urlwith your webhook.site URL andYOUR_API_KEY_HEREwith your Vizion API key.
curl --location 'https://prod.vizionapi.com/references' \
--header 'X-API-Key: YOUR_API_KEY_HERE' \
--header 'Content-Type: application/json' \
--data '{
"container_id": "MEDU8381210",
"carrier_code": "MSCU",
"callback_url": "https://webhook.site/8c650d00-aa31-4a4b-a483-1fcc88e4337d"
}'
- Replace the
container_idandcarrier_codevalues with your own shipment information or use the example data above. - Open your terminal, paste the complete cURL request, and press Enter.
- You will see a response indicating that the request was successful with information about the reference created.
// Successful reference creation response in the terminal
{
"message": "Reference created successfully.",
"reference": {
"id": "ef37bc21-e65e-46cc-8f2b-ef66a32e5a76",
"container_id": "MEDU8381210",
"bill_of_lading": null,
"booking_number": null,
"carrier_scac": "MSCU",
"callback_url": "https://webhook.site/8c650d00-aa31-4a4b-a483-1fcc88e4337d",
"organization_id": "777ccf97-c75b-4051-893b-a47a367bf185",
"parent_reference_id": null,
"latest_update_id": null,
"carrier_id": 6,
"active": true,
"auto_carrier": false,
"last_update_status": null,
"created_at": "2023-11-28T01:53:03.669Z",
"updated_at": "2023-11-28T01:53:03.669Z",
"last_update_attempted_at": null,
"next_scheduled_update_attempt_at": null,
"process_frequency_minutes": null,
"retry_count": 0,
"simple_tracking": false,
"shipment_completed": false,
"auto_unsubscribed": false
}
}
Check callback URL for update
Now that the reference is created, check your webhook.site URL for the update payload information. This data, in JSON format, describes where the container you are tracking is in the world. You can expect to receive this first update within 30 seconds of making your API request. You will then receive further updates when new data is available.
At your webhook.site URL, select the top POST request in the list to the left. Scroll down to see the JSON delivered by Vizion containing event milestones relevant to the container you are tracking. You have successfully created your first reference! For a full explanation of what this data means, we recommend reading more about understanding the update payload.
 <<glossary:callback URL>>](https://files.readme.io/5632813-Screen_Shot_2023-11-27_at_5.59.14_PM.png)
🎉 Now that you are successfully subscribed to this reference, you will continue to receive updates as the container moves along its journey until it is auto-unsubscribed or you unsubscribe using the Unsubscribe reference endpoint.
Retrieve reference status
If you ever encounter a situation where you haven't received data for a specific reference and would like to investigate further, you can utilize the Get reference endpoint. This endpoint allows you to check the status and gather more information about the reference in question.
- First, copy the
reference_idfrom the previous step within the JSON payload. - Below, replace
REFERENCE_IDin the URL with the reference ID you have copied andYOUR_API_KEY_HEREwith your API key.
curl --location 'https://prod.vizionapi.com/references/REFERENCE_ID' \
--header 'X-API-Key: YOUR_API_KEY_HERE'
- Copy the request into your terminal and press Enter. The JSON response provides detailed information about the status of your reference, including the last update status (
last_update_status). For more information about what each status means, please refer to the check reference status troubleshooting article.
{
"id": "ef37bc21-e65e-46cc-8f2b-ef66a32e5a76",
"container_id": "MEDU8381210",
"bill_of_lading": null,
"booking_number": null,
"carrier_scac": "MSCU",
"callback_url": "https://webhook.site/8c650d00-aa31-4a4b-a483-1fcc88e4337d",
"organization_id": "777ccf97-c75b-4051-893b-a47a367bf185",
"parent_reference_id": null,
"organization": {
"id": "777ccf97-c75b-4051-893b-a47a367bf185",
"name": "Organization",
"active": true,
"created_at": "2023-01-25T18:46:49.676Z",
"updated_at": "2023-10-10T01:01:35.560Z"
},
"carrier_id": 6,
"carrier": {
"id": 6,
"name": "MSC",
"code": "MSCU",
"enabled": true
},
"active": true,
"auto_carrier": false,
// Last update status is data received indicating the data was delivered to the <<glossary:callback URL>> successfully
"last_update_status": "data_received",
"created_at": "2023-11-28T01:53:03.669Z",
"updated_at": "2023-11-28T01:53:06.114Z",
"last_update_attempted_at": "2023-11-28T01:53:03.935Z",
"retry_count": 0,
"child_reference_ids": []
}
View all references you are currently tracking
To see all the references associated with your API key, you can use the List active references endpoint. The response will include an array of reference objects, allowing you to easily view all the active references currently associated with your account.
- Copy the cURL request below and replace
YOUR_API_KEY_HEREwith your API key. - The JSON response returned will contain an array of all reference objects you are currently tracking.
curl --location 'https://prod.vizionapi.com/references' \
--header 'X-API-Key: YOUR_API_KEY_HERE'
{
"id": "ef37bc21-e65e-46cc-8f2b-ef66a32e5a76",
"container_id": "MEDU8381210",
"bill_of_lading": null,
"booking_number": null,
"carrier_scac": "MSCU",
"callback_url": "https://webhook.site/8c650d00-aa31-4a4b-a483-1fcc88e4337d",
"organization_id": "777ccf97-c75b-4051-893b-a47a367bf185",
"parent_reference_id": null,
"organization": {
"id": "777ccf97-c75b-4051-893b-a47a367bf185",
"name": "Organization",
"active": true,
"created_at": "2023-01-25T18:46:49.676Z",
"updated_at": "2023-10-10T01:01:35.560Z"
},
"carrier_id": 6,
"carrier": {
"id": 6,
"name": "MSC",
"code": "MSCU",
"enabled": true
},
"active": true,
"auto_carrier": false,
"last_update_status": "data_received",
"created_at": "2023-11-28T01:53:03.669Z",
"updated_at": "2023-11-28T01:53:06.114Z",
"last_update_attempted_at": "2023-11-28T01:53:03.935Z",
"retry_count": 0,
"child_reference_ids": []
},
{
"id": "1f95ae71-5cbd-4c77-9c90-2c856e17eb03",
"container_id": "MEDU8381210",
"bill_of_lading": null,
"booking_number": null,
"carrier_scac": "MSCU",
"callback_url": "https://webhook.site/#!/92cc0ca9-37d7-417e-8afd-baa6b2bb0d23",
"organization_id": "777ccf97-c75b-4051-893b-a47a367bf185",
"parent_reference_id": null,
"organization": {
"id": "777ccf97-c75b-4051-893b-a47a367bf185",
"name": "Organization",
"active": true,
"created_at": "2023-01-25T18:46:49.676Z",
"updated_at": "2023-10-10T01:01:35.560Z"
},
"carrier_id": 6,
"carrier": {
"id": 6,
"name": "MSC",
"code": "MSCU",
"enabled": true
},
"active": true,
"auto_carrier": false,
"last_update_status": null,
"created_at": "2023-11-28T01:52:09.400Z",
"updated_at": "2023-11-28T01:52:09.400Z",
"last_update_attempted_at": null,
"retry_count": 0,
"child_reference_ids": []
},
{
"id": "1d9e7094-25b2-47f7-8c3f-c0f786cded1d",
"container_id": "MEDU8381210",
"bill_of_lading": null,
"booking_number": null,
"carrier_scac": "MSCU",
"callback_url": "https://webhook.site/92cc0ca9-37d7-417e-8afd-baa6b2bb0d23",
"organization_id": "777ccf97-c75b-4051-893b-a47a367bf185",
"parent_reference_id": null,
"organization": {
"id": "777ccf97-c75b-4051-893b-a47a367bf185",
"name": "Organization",
"active": true,
"created_at": "2023-01-25T18:46:49.676Z",
"updated_at": "2023-10-10T01:01:35.560Z"
},
"carrier_id": 6,
"carrier": {
"id": 6,
"name": "MSC",
"code": "MSCU",
"enabled": true
},
"active": true,
"auto_carrier": false,
"last_update_status": null,
"created_at": "2023-11-28T01:51:02.211Z",
"updated_at": "2023-11-28T01:51:02.211Z",
"last_update_attempted_at": null,
"retry_count": 0,
"child_reference_ids": []
},
...
Next steps
In this tutorial, you learned how to use the Container Tracking API to subscribe to a container. By utilizing the command line and cURL, you accessed the API and created a callback URL to receive realtime data updates through webhooks. With these steps, you can effectively track containers and receive updates throughout their journey. Check out our Input options for tracking containers and Use the Vizion Postman collection for more introductory material.
Updated 7 months ago