Vizion
Table of Contents
Vizion is a ruby gem client library for talking to VIZION API built using OpenStruct so you can easily access data in a Ruby-ish way.
Installation
Add this line to your application’s Gemfile:
gem 'vizion'
And then execute:
bundle
Or install it yourself as:
gem install vizion
Usage
You’ll need to generate an api key: https://vizionapi.com/sign-up Initialize client and making request:
require 'vizion' client = Vizion::Client.new(api_key: "X-API-Key", timeout: 10) client.carriers
Resources
Carriers
List of all supported carriers, to view the list click here.
Actions supported:
client.carriers.list
References
Actions supported:
client.references.list
client.references.retrieve(id)
client.references.updates(id)
client.references.create({})
client.references.delete(id)
Pagination
Use the page query parameter to set the current page (default: 1)
Use the per_page query parameter to set a per page limit (default: 25)
client.references.list(per_page: 10, page:2)
Create Reference with Auto Carrier Identification.
Add container reference for update tracking without a carrier code. To do this, provide only a container_id with in the body request payload. Please note, it will always be faster and more accurate to provide a carrier code when you can.
VIZION API will periodically check for updates and send updates via HTTP POST to the provided callback_url parameter.
Raw body
{
"container_id": "CMAU4049810",
"callback_url": "https://yourdomain.com/webhook"
}
Ruby way
client.references.create(container_id: "CMAU4049810", callback_url: "https://yourdomain.com/webhook")
Create Reference with Carrier Code
Add container reference for update tracking using a carrier code.
Raw body
{
"container_id": "CAIU4482704",
"carrier_code": "HDMU",
"callback_url": "https://yourdomain.com/webhook"
}
Ruby way
client.references.create(container_id: "CMAU4049810", carrier_code: "HDMU", callback_url: "https://yourdomain.com/webhook")
If no callbackurl parameter is provided, you will need to fetch status updates from the referenceupdates action.
Milestones event names
Here you can find information on how Vizion standardizes event names.
| Milestones Event Name | Description |
|---|---|
| Available for release / delivery | Released by carrier |
| Barge arrived | Container has been moved by barge to next point of transit |
| Barge departed | Barge is en route to next destination |
| Carrier release | Cargo can be picked up by consignee |
| Customs release | Container has cleared customs |
| Delivered | Container has been delivered to destination |
| Discharged from barge | Container is no longer on the barge |
| Discharged from feeder | Container is no longer on the feeder will move by next mode of transportation |
| Discharged from rail | Container is no longer on the rail |
| Discharged from truck | Container is no longer on the truck |
| Discharged from vessel | Container is no longer on the vessel |
| Discharged from vessel at transshipment port | Container is no longer on the vessel and is in transit to the next mode of transport |
| Discharged transshipment | Container is no longer on the vessel |
| Estimated arrival at destination | Estimated time vessel will arrive at destination port |
| Estimated Time of Arrival | Estimated time vessel will arrive at destination port |
| Feeder arrived | Feeder has arrived at port |
| Feeder departed | Feeder has departed port |
| Gate in | Container is checked in at either port of origin or destination |
| Gate in at destination port | Container is checked in at destination port |
| Gate in at inland destination | Container is checked in at an inland location |
| Gate in at origin port | Container is checked in at port of origin |
| Gate in empty | Container is returned empty after being used - goods are emptied and container is returned |
| Gate in empty return | Container is returned empty after being used - goods are emptied and container is returned |
| Gate in full | Container has been loaded and is ready to board the vessel |
| Gate out | Container has left the terminal |
| Gate out empty | Empty container has been picked up. This starts the clock for detention (equipment) |
| Gate out from destination port | Container has left the destination port |
| Gate out from origin port | Container has left the terminal |
| Gate out to consignee | Consignee (person consigner shipped goods to) picked up the container |
| Loaded | Container is loaded on the vessel |
| Loaded on barge | Container is loaded on the barge |
| Loaded on feeder | Container is loaded on the feeder |
| Loaded on rail | Container is on the rail |
| Loaded on rail at destination port | Container is on the rail at the destination port |
| Loaded on truck | Container is on the truck |
| Loaded on vessel | Container is on the vessel |
| Loaded on vessel at origin port | Container is on the vessel at origin |
| Loaded on vessel at transshipment port | Container has moved to transshipment port and is loaded on the vessel |
| Loaded transshipment | Container has moved to transshipment port and is loaded on the vessel |
| Picked up by customer | The customer has picked up the container |
| Rail arrived | Container is on the rail and has arrived at next point |
| Rail demurrage notice | Rail company has issued a notice regarding demurrage |
| Rail departed | Container is on the rail and has departed |
| Rail departed from inland origin | Container is on the rail and has departed from the inland origin |
| Stripping empty | Cargo has been removed from container and has been cleaned |
| Stuffing | Container is being loaded with cargo, usually at the warehouse or by truck at the terminal |
| Transshipment delay | Container is experiencing delays at the transshipment port |
| Truck arrived | Truck is at the terminal to pick up container |
| Truck delivery scheduled | Truck has made appointment to deliver container |
| Truck departed | Truck has departed the terminal |
| Truck pickup scheduled | Truck has scheduled an appointment with the terminal to pick up the container |
| Vessel arrival | Vessel has arrived at the port |
| Vessel arrival at transshipment port | Vessel has arrived at the transshipment port |
| Vessel arrived | Vessel has arrived at the port |
| Vessel arrived at destination port | Vessel has arrived at the destination port |
| Vessel arrived at origin port | Vessel has arrived at the origin port |
| Vessel berthed in port | Vessel has berthed or arrived at designated port at the terminal. Container should be available for pick up |
| Vessel departed | Vessel has departed the port |
| Vessel departure from origin port | Vessel has departed from the origin port |
| Vessel departure from transshipment port | Vessel has departed from the transshipment port |
| VGM received | VGM (verified gross mass) paperwork is in order |
Contributing
Everyone is encouraged to help improve this project. Bug reports and pull requests are welcome at https://github.com/vertilux/vizion/pulls. Feel free to open an issue to get feedback on your idea before spending too much time on it.
License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).