Vizion

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 callback_url parameter is provided, you will need to fetch status updates from the reference_updates 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).

vizion

Runtime