Introduction
NowGo allows you to create and schedule logistics jobs, and to modify those schedules in real time. The NowGo optimisation engine enhances this capability with best-in-class vehicle routing AI. The NowGo API gives you programmatic access to all this functionality.
Key Concepts
Stops and Jobs
Example Stop
"...deliver the package to 12 Smith St on the afternoon of January 1st..."
The key unit of work in NowGo is the stop.
A Stop represents a requirement to send a driver to a particular location, subject to constraints. NowGo will achieve this goal as efficiently as possible.
A stop might be a pickup, or a delivery, or even a service call. Stops have a single location, a service time, and a window of time when they can be performed. It's also possible to add other requirements, like a specific driver.
Example Job
"...collect the package from the depot before midday of January 1st, and deliver it to 12 Smith St that afternoon..."
The example job above would consist of two stops, in order: collection at the depot, and delivery to 12 Smith St.
A Job groups stops together. Each stop belongs to exactly one job; each job may contain any number of stops. All the stops in a job will be performed by the same driver.
A pickup from one location and delivery to another is a job, consisting of two stops. An assistant collecting money to be deposited, doing so at the bank, and returning to the office is a job with three stops. A service call is also a job, but has only a single stop.
Shifts
Example Shift
"...Andrew has a shift from 10:00am until 6:00pm on 1 Jan..."
A Shift represents a period of time in which a driver is working in the NowGo system. Shifts tell the system when drivers can be scheduled to complete stops.
You can think of a shift like an itinerary or runsheet, with a starting time and list of work to do. NowGo will work out who should do what, and when.
Stops and Shifts
Stops are assigned to shifts for completion, either automatically by the system or manually by a dispatcher.
Stops can be assigned to at most one shift at a time. A stop not assigned to any shift is said to be unassigned
.
Drivers and Vehicles
Example Driver and Vehicle
"...We've assigned the 9am Melbourne run to Cheryl, in the fridge truck..."
Drivers and Vehicles are the real-world resources used to complete jobs. Shifts can be assigned to a driver and a vehicle.
When a driver is assigned a shift, they can use the driver app to see the stops scheduled in that shift, and complete them. Scheduled stops will also have an ETA. Dispatchers can change the order of planned stops, and the app will show the changes.
Further Concepts
Plans
When optimising vehicle movements, sometimes the world changes very quickly. It is important to maintain a stable view of the world, so that changes can be made in a reasonable way. Plans are used to take a snapshot of the state of a channel, so that the solver or a user can change it without having to deal with concurrent world events.
Plans can capture either the full state of a channel in a given window of time, or a view of specific jobs and channels. This allows plans to be created with fine-grained contents, allowing a single shift to be optimised without dealing with concurrent effects.
Plans can also be merged back into the world. This will update the world with the changes made in the plan. If stops have been completed in the world since being added to the plan, they will not be reassigned to shifts.
Sometimes, a plan cannot be merged if the world has changed too much since the plan was created. For example, the plan may have assigned stops to a shift that has been cancelled. In these cases, the plan is conflicting and cannot normally be merged.
Solves
When working inside a Plan, you can instruct NowGo to apply its optimisation engine to the contents of that plan. Depending on the preferences chosen, this will change the plan in different ways. The specifics of available solves are detailed in the documentation for the solve creation endpoint.
When you start a solve, the response contains an object documenting the current state of that solve. Solves complete asynchronously, so it is necessary to poll the object if you wish to wait for the solve to finish.
Capacities
Example Capacity
"...large vans have a maximum cargo capacity of 6 m^3..."
"...carrying that consignment will take 2 m^3 of space..."
In the above example, the capacity is the cargo capacity of the vehicle. The van has a capacity limit of 6. The consignment has a capacity cost of 2.
When optimizing logistics decisions, it is often necessary to consider capacity limits. These can be quantities that rise and fall below a certain threshold, or quantities that only increase.
An example of a rising and falling capacity is the weight carried by a vehicle. When the vehicle takes on cargo, the carried weight increases. When the vehicle offloads cargo, the carried weight decreases again.
An example of a rising capacity is a limit on the number of jobs a driver can perform in a day. As the driver completes jobs, the number rises. There's no way that the number of jobs performed can decrease.
NowGo treats capacities as first-class objects. Capacities have ids, and names. Stops can have capacity costs, which indicate that the stop will use a certain quantity of the relevant capacity. Vehicle types can have capacity quantities, which indicate that a limited quantity of the capacity is available. If no capacity quantity is set, the capacity is assumed to be infinite.
Capacity costs can be negative. When completing a stop that adds weight to a vehicle, for instance, the stop has a weight cost of 4
. The next stop in the job that delivers that cargo would have a weight cost of -4
.
If the capacity you're representing is a weight, you can configure capacities to display in specific units on the app and dashboard. Internally, these capacities use a quantity in milligrams that is converted for display.
Attributes
Example Attributes
Boolean: "...is the vehicle refrigerated?..."
Numeric: "...how much weight can the tailgate lift? ..."
In addition to capacity limits, vehicles and vehicle types can also have attribute values. Whereas a capacity limit describes a finite resource which may be exhausted (e.g. by loading a vehicle until its weight capacity is reached), an attribute value is constant (a refrigeration truck remains refrigerated regardless of the load).
Example values for Attributes
Boolean: "...that job's vehicle is refrigerated..."
Numeric: "...and has a 50kg tailgate ..."
In the above example, the shift's vehicle is refrigerated and hence suitable for carrying frozen goods, and has a tailgate that can lift 50kg.
Each vehicle or vehicle type may define a value for a given Attribute. For example, a specific vehicle type may be refrigerated and have a tailgate with a load capacity of 50kg. A vehicle type must have at most one value per attribute. For example, a vehicle type cannot both have a 50kg tailgate and a 100kg tailgate.
Attributes are first-class values and can be retrieved via attribute endpoints. Attribute values are not first-class objects. Attribute values are created implicitly when creating vehicles or vehicle types (via the 'attribute_values' field), and are returned as part of the vehicle or vehicle type JSON object.
Show me the Vehicle Types API that includes attribute values Show me the Vehicles API that includes attribute values
Example Attribute requirements
Boolean: "...since this job transports frozen goods, a refrigerated vehicle is required..."
Numeric: "...and because heavy goods are to be loaded, it must have a tailgate able to lift at least 40kg ..."
In the above example, any vehicle to be assigned to the job must be refrigerated and must have a tailgate capable of lifting at least 4kg. Because the vehicle type described in Example Attributes meets these requirements, it can be considered for this job.
Vehicle and vehicle type attribute values are checked on a per-job basis against a job's vehicle requirements. A job can have zero or more requirements, each of which will be a condition that will be tested for any vehicle or vehicle type candidates for that job. Only vehicles or vehicle types meeting all of a job's requirements will be considered for that job. Vehicle requirements are not first-class objects and are created and queried as part of their parent job.
Requirement types: - Boolean requirement - test whether a vehicle or vehicle type's value for that attribute matches the requirement's value. As an example, a vehicle with an Attribute Value of 'true' for the Attribute 'is-refrigerated' can carry out jobs with a requirement of having 'is-refrigerated' be 'true' - Numerical requirements - test whether a vehicle or vehicle type's value for that attribute is (less than or equal to max, greater than or equal to min, between min and max) to the requirement's value. As an example, a vehicle with an Attribute Value of 5 will not be considered for a job which has a less-than requirement for that Attribute of 4, since 5 is greater than 4.
Show me the Jobs API that includes requirements
Vehicle Types
Example Vehicle Type
"...that shift's vehicle is a small truck..."
NowGo models groups of vehicles via vehicle types, such as defining a 'motorbike' vehicle type to group all motorbikes. Vehicle types can be used to constrain which vehicles are chosen for a job; for example, the 'motorbike' vehicle type can be used to indicate that motorbikes should be preferred to perform deliveries in the CBD. Vehicle types also allow the definition of common attributes and capacity limits that apply to a group of vehicles.
Vehicle types are first-class objects and can be referred to by id or by ext_ref.
Vehicle types can be used for preferences, and for requirements. A positive
preference means that a vehicle type should perform a particular job if possible. A negative
preference means that a particular vehicle type should not perform a particular job, unless doing so would reduce completion rates. Vehicle type requirements mean that a particular vehicle type must perform the given job.
Vehicle types can have capacity limits associated with them. For example, large vans may be able to carry a certain volume of cargo. Vehicles can also have attribute values associated with them. For example, given an attribute 'is-refrigerated', a vehicle may have the value 'true' indicating that it is a refrigerated vehicle.
Vehicles
Example Vehicle Type
"...that shift's vehicle is one of our refrigerated trucks, 'RefrigeratedTruck3'."
Vehicles are individual instances of a vehicle type. For example, a generic refrigerated truck may be represented by a vehicle type 'refrigerated-truck' with an attribute 'is-refrigerated' that is set to 'true'. A vehicle with the 'refrigerated-truck' vehicle type represents a concrete instance of this abstract vehicle type. Any number of vehicles can have the same vehicle type. All these vehicles inherit the vehicle type's attribute values and capacity limits. In the example of the 'refrigerated-truck' vehicle type, any vehicles using it will have an attribute value 'is-refrigerated' set to 'true'.
In addition to inheriting attribute values and capacity limits from the vehicle type, vehicles can also define additional attribute values and capacity limits which apply only to that vehicle. If an attribute value or capacity limit is defined for both the vehicle type and the vehicle, then the vehicle's value will be used instead of the parent's value. As an example, if the vehicle's vehicle type has an attribute value 'refrigerated' that is set to 'true' and the vehicle itself also has the 'refrigerated' attribute value, but set to 'false', then the vehicle's 'refrigerated' attribute will be 'false'.
Vehicles can also 'delete' their parent type's attribute value or capacity limit by omitting the 'value' or 'limit' field. This means the vehicle will not inherit its parent type's attribute value or capacity limit. For example, deleting the 'cargo-volume' capacity limit on a vehicle means the vehicle will not have a 'cargo-volume' capacity limit even if its vehicle type defines one.
Vehicles are first-class objects and can be referred to by id or by ext_ref. Just as it is possible to filter vehicle types using vehicle type preferences, vehicles can be filtered using vehicle preferences. Job attribute requirements are used to filter both vehicles and vehicle types.
Locations
Example location
"This particular location is a depot."
Locations are addresses or coordinates associated with a real-world place. The location object can be used to create something like an address book where destinations can be recorded along with other useful information.
Location objects can be used to create stops and pre-fill the address and coordinate fields by referring to them using an id or external reference. For details on this see the stops section.
Location Groups
Example Location Group
"Whenever you do work at the port, always allow 30 minutes for parking."
Location Groups are used to indicate that multiple stops are performed at a similar location. For example, a location group could be created to mark all stops at a particular port.
Location Groups can have time costs associated with them, which are applied only once whenever multiple stops in the group are performed together. For example, the port location group mentioned above may have a time cost of thirty minutes, to represent the waiting time to enter the port. This cost is only incurred once each time multiple stops at the port are performed.
The system will consider the benefits of performing stops with a location group time cost at the same time when optimizing. Location group time costs are also reflected in ETA and travel calculations.
Show me the Location Groups API
Annotations
Example Annotation
"... the driver commented on this job, saying that the package was left at the door..."
"... the driver noted that this job included a 30 minute wait time..."
In the above examples, these two statements can be expressed as two annotations associated with the job. The annotations could be called
Driver Comments
andWaiting Time
. Annotations provide a way for drivers to input information about specific jobs as they are performed in the field.
Annotations are driver editable attachments to job objects.
An annotation consists of two parts. The first is the annotation type which specifies the name
of this field, such as "Notes", "Waiting Time", "Service fee", etc. Annotation types are first-class objects and can be referred to by id
or by ext_ref
.
The second object is the annotation value which specifies the value of annotation for a particular job. This is also a first-class object, indexed by job id and annotation type id.
Stop dependencies
Example Stop Dependencies
"... the line-haul driver will drop off the container at the warehouse, then the local drivers can pick up these packages ..."
"... these two drivers will meet at the designated location to transfer the package ..."
Stop dependencies are the mechanism that NowGo uses to represent the requirement that one stop must only be completed after (or perhaps at the same time as) a stop in another job. When representing a stop dependency, there is an explicit "dependent" stop, and "precursor" stop, even if these stops are meant to occur at the same time. Stop dependencies are attached to the dependent stop, and stop dependencies can only be modified by making changes to the dependent stop.
A common use case for stop dependencies is when two drivers are involved in the delivery of the same consignment. Here there would be an implicit relationship between the stops in these jobs, whereby the delivery of the first job must come before the pickup of the second.
In some instances, two stops must occur at the same time, such as in a transfer or an assisted job. In these instances, it is possible to flag a stop dependency as having the additional requirement that both the precursor stop and the dependent stop must have the same starting time.
Consignments
"... my goods are travelling as one consignment between Sydney and Melbourne ..."
A Consignment represents one or more physical items in the system that are generally intended to travel as a group with the same purpose, and it includes contextual information about the movement.
Articles
"... there are 4 articles on this consignment ..."
An Article directly represents a trackable physical object. One or more of these make up a Consignment.
The item count is used in the case that not all real-world objects have a trackable ID. In this case one trackable object, the article, can be used to represent more than one physical item.
Workflow completions
"... a workflow completion was created when the driver finished the delivery workflow ..."
"... a workflow completion was created by the integration when the consignment was scheduled in a run ..."
"... a workflow completion completed 3 stops related to the target consignment ..."
A workflow completion represents an event in NowGo. They are created when a driver completes a workflow on the NowGo app, or directly through the API.
The creation of a workflow completion can trigger a number of additional interactions in NowGo, including:
- Creating stop completions.
- Creating and updating consumer tracking sessions.
- Triggering communications with consumers.
- Updating a driver's onboard register.
Workflow completions and consignments
Articles that a workflow interacts with are referred to as the subject articles of a workflow completion.
Interactions with target articles can trigger events relating to the target article's consignments such as updates to consumer tracking sessions and stop completions.
Workflow completions and drivers
When a driver completes a workflow in the NowGo app, this will create a workflow completion that contains driver-related information:
- An id or external reference for the driver that completed the workflow.
- A device id for the device used to complete the workflow.
- A local device id for the workflow completion.
- An id for the shift the driver completed the workflow in.
- Any attachments that were created during the workflow, which may include proof of delivery photos and signatures.
- The latitude and longitude of where the workflow completion occurred, where available.
The driver's onboard register may also update if the workflow completion has subject consignments and articles.
Workflow completions and stops
A workflow completion can contain stop completions. When a workflow completion is created with stop completions objects they are created in NowGo, updating the completion status of the relevant stops.
Actions
"... when a driver scans this article, they need to complete the "onboard" action ..."
"... a new custom action has been added to the app ..."
"... the deliver action was unsuccessful with outcome
deliver_failure_no_atl
..."
An action represents an operation associated with an article and by extension, consignments, stops and jobs.
When a driver scans an article in the NowGo app, they are presented with a list of actions. If no custom actions are set, a default set of actions are shown which are:
- Pickup
- Dropoff
- Onboard
- Offboard
- Sort
Custom actions can be set to override the behaviour of a default action or to create a completely new flow in the app (although this requires Thunder configuration).
Actions will have an associated outcome once completed. Outcomes are either successful or unsuccessful and can contain some context around why the outcome happened.
API Basics
The NowGo API is provided via HTTP (over SSL). Most programming languages will have an HTTP client library that can be used to access the NowGo API.
Some examples given below are cURL statements. You can run them on a command line to try out different API requests.
Beside each endpoint is a descriptor such as GET /drivers
or POST /shifts
. The first word indicates the type of HTTP request to send to that endpoint (e.g. GET for accessing resources, and POST for creating them). The remainder is a partial URI, which should be prefixed with https://api.nowgo.io/v0/
to get the full URL for that endpoint.
E.g. to access an endpoint described in the documentation as GET /drivers
, you would send a GET request to https://api.nowgo.io/v0/drivers
.
Curly braces indicate placeholders for more specific values (path parameters).
E.g. the endpoint GET /shifts/{id}
views details a shift with a given ID. To access details for the shift with ID 123, you would send a GET request to https://api.nowgo.io/v0/shifts/123
.
Security and authentication
The API is accessed over SSL only. You must have an API token issued by Premonition for your organisation's NowGo account.
Requests are authenticated using basic authentication, with the API token as the password and the username left blank.
For example, if your API token is e3b0c442
, you might run:
curl -u :e3b0c442 https://api.nowgo.io/v0/drivers
Obtaining API tokens
API tokens are issued on request by Premonition. Speak to your Premonition contact for more details.
Request format
The NowGo API is a JSON API. You must supply a Content-Type: application/json
header in POST requests. You must set an Accept: application/json
header on all
requests.
Some errors (e.g. bad URL) may produce a text/plain
response.
Response format
When you create or update a resource, NowGo returns a JSON representation of the (updated) resource in the response body.
Errors
The NowGo API uses HTTP response codes to specify the success or failure of a request.
Following convention, 2xx
codes indicate success, 4xx
indicate an error originating with the request,
and 5xx
indicate a server-side error. In general, 4xx
errors are returned with a JSON object
with a short message indicating what was wrong, and if possible, which parameter and value failed.
Rate Limiting
To ensure that we can maintain a high level of availability, limits are in place for the rate at which we service requests to our API. The limits we enforce may vary over time in response to changing conditions.
If an API request exceeds rate limits, a 429 Too Many Requests
response will be returned. This response includes a
Retry-After
header with the number of seconds a client should wait before attempting another request.
Rate limits are currently enforced per org, and read-only requests are considered separately from requests that make changes.
Timestamps and timezones
An ISO8601 timestamp in UTC
2000-01-01T00:00:00.0000Z
When the NowGo API needs to send or receive timestamps, we use ISO 8601 unless otherwise specified. Timestamps we produce will always be in UTC with an explicit time designator (Z
or +00:00
).
If data includes a specific time zone, it will be included as a separate field. We use the IANA time zone database as our source for time zones.
If you're displaying timestamps to users, you should normalise them to a human-readable format, including changing the time zone to what your users might expect.
If you're loading timestamps from NowGo to another system, you should transform them to the format and time zone that the system expects.
Pagination
Example request
curl -u :{auth_token} 'https://api.nowgo.io/v0/channels'
Example response
The request has returned the first page of data, and a
next_page_token
that can be used to fetch subsequent pages.
{
"data": [
{
"id": "193",
"name": "West"
}
],
"next_page_token": "7f42d53f"
}
Request for next page
curl -u :{auth_token} 'https://api.nowgo.io/v0/channels?page_token=7f42d53f'
Response for next page
The request hasn't returned a
next_page_token
, so this is the final page of data.
{
"data": [
{
"id": "254",
"name": "South"
}
],
"next_page_token": null
}
Sometimes, an endpoint might need to return multiple objects in a list. The NowGo API paginates data to keep query time and response sizes manageable.
Our standard pagination mechanism is token-based. Requests that return lists of objects might also have a
next_page_token
. If a response has a next_page_token
, there might be more data to fetch - repeat the request
with the page_token
query parameter set to the next_page_token
you just received.
If a response has next_page_token = null
, then there's no more data to fetch.
Each next_page_token
is intended to be opaque to the caller. The implementation and contents may vary per-endpoint
and over time. Tokens should be used soon after they are fetched, and they aren't guaranteed to be ordered.
You can also pass page_size
as a parameter. If you don't, we'll use a default size. If you request a page size that's
larger than we support, we'll return as large a page as we can.
Pagination - cursor-based (legacy)
This method of pagination is being phased out. See the above Pagination section
Example request
curl -u :{auth_token} 'https://api.nowgo.io/v0/stops/bad-geocodes?limit=3'
Example response (default cursor)
In the below example, we made a request with a limit of three and without specifying a cursor position. Three results were found, and the
has_more
parameter wastrue
indicating that more results were found. If no cursor position is specified usingstarting_after
orending_before
, the most recently created results will be displayed in ascending order with the most recent at the end of the list. We can retrieve more of the list by specifyingending_before = 193
{
"data": [
{
"id": "193",
"location": {}
},
{
"id": "194",
"location": {}
},
{
"id": "195",
"location": {}
}
],
"has_more": true
}
Example request (looking backwards)
curl -u :{auth_token} 'https://api.nowgo.io/v0/stops/bad-geocodes?limit=3&ending_before=193'
Example response
In this example, we made a request with a limit of three and with explicitly specifying a cursor position using
ending_before
to look backwards through the entire collection of stops. Three results were found, and thehas_more
parameter was false indicating that no more results were found ending before the start of this list.
{
"data": [
{
"id": "190",
"location": {}
},
{
"id": "191",
"location": {}
},
{
"id": "192",
"location": {}
}
],
"has_more": false
}
Example request (looking forwards)
curl -u :{auth_token} 'https://api.nowgo.io/v0/stops/bad-geocodes?limit=2&starting_after=192'
Example response
In this example, we made a request with a limit of two and with explicitly specifying a cursor position using
starting_after
to look forwards through the entire collection of stops. We get a page starting after our previous request by specifying the lastid
in that page. Two results were found, and thehas_more
parameter was true indicating that there are more results starting after the end of this list.
{
"data": [
{
"id": "193",
"location": {}
},
{
"id": "194",
"location": {}
}
],
"has_more": true
}
The NowGo API separates the results of endpoints that provide a list of things
(such as listing invalid stop locations) into pages.
These pages can be navigated and specified using the limit
, starting_after
and ending_before
query parameters. The position of the current page is
described using a cursor specified using the starting_after
and ending_before
parameters.
Specifying the limit
parameter will set the number of items in a page
received in each request. Pages can be navigated by specifying the starting_after
and ending_before
parameters. Both take an existing object ID value in either
a numeric or UUID format depending on the object.
The ending_before
parameter returns objects created before the named object.
The starting_after
parameter returns objects created after the named object.
If both parameters are provided, only ending_before
is used.
If neither parameter is provided, the default cursor is used.
In many endpoints, the default cursor is the equivalent of the back page of
a book, containing the most recently created resources.
In this case, we can view the entire list of resources by starting at the default
last page and reading backwards by subsequently setting the ending_before
parameter to the id at the head of each list.
The input parameters are:
- limit
: An integer between 1 and 100, specifying the maximum number of items
returned by each request. The default value is 10.
The JSON message returned will contain the following entries:
data
: A list containing the requested results.has_more
: A boolean specifying if there are more results to be fetched.
Pagination - page-based (legacy)
This method of pagination is being phased out. See the above Pagination section
Endpoints that provide a list of things (e.g. "List all drivers") provide a default of 10 results per page. To see subsequent pages, set the page
parameter in the request URL parameters. Pages are numbered starting at 1.
Example request
curl -u :{auth_token} 'https://api.nowgo.io/v0/drivers?page=2&perPage=1'
Example response
{
"page": 2,
"totalPages": 11,
"totalResults": 11,
"results": [
{
"id": 6,
"name": "Phillip Jones",
"email": "phillip@jones.example.com",
"enabled": true
}
]
}
You may also set the perPage
parameter in the request URL parameters, which alters the number of results shown per page. Most endpoints will enforce limits on the number of items returned per page.
The JSON message returned will contain the following entries:
page
: The page number requested. (Defaults to 1 if none given.)total_pages
: The number of available pages of results (i.e. the highest page that can be sensibly requested).total_results
: The total number of results available.results
: An array containing the requested results.
Updating resources
Example driver object
{
"id": "15114",
"ext_ref": "syd01D",
"name": "John Smith",
"email": "john.smith@example.com",
"color": "red"
}
Partial update with PATCH
$ curl https://api.nowgo.io/drivers/15114 \
-X PATCH \
-u :{auth_token} \
-d
{
"name": "John Smyth",
"email": null
}
Resulting object
{
"id": "15114",
"ext_ref": "syd01D",
"name": "John Smyth",
"color": "red"
}
This example request contained a
name
field, so thename
of the driver was updated. Thenull
, so the driver's email was cleared. Thecolor
field was not in the request, and so was not changed in the object.
Where possible, updates to resources are performed using a PATCH
command. This is to help ensure that existing implementations remain compatible with future versions of the API. PATCH
allows partial updates to a resource by selectively including or omitting values in the request body.
The NowGo PATCH
implementation follows RFC7396 Json Merge Patch.
External references
Successful request
> POST /stops/
> { "ext_ref": "only-one" }
< 200 Ok
Conflicting request
> POST /stops/
> { "ext_ref": "only-one" }
< 200 Ok
> POST /stops/
> { "ext_ref": "only-one" }
< 409 Conflict
NowGo uses its own internal ID numbers for most resources. To simplify integration with external systems, NowGo allows some types of resources to include an external reference. These can be used later to look up those resources.
External references:
- Must be unique - no two resources of the same type can have the same external reference.
- Are written once and cannot be changed, expect in special cases.
- Cannot be reused even if the resource is deleted, unless otherwise specified.
External references are formed from a subset of url safe characters - valid characters are:
- uppercase and lowercase letters
[A-Za-z]
- decimal digits
[0-9]
- hyphen
-
- period
.
- underscore
_
- tilde
~
External references can be up to 64 characters in length.
When the external reference provided for a created object conflicts with an already existing external reference, a 409 Conflict
response containing the conflicting object will be returned.
Accessing resources using external references
Example GET request using an external reference
# curl https://api.nowgo.io/v0/jobs/ext-ref/job-123 \
-u :{auth_token}
Example PATCH request using an external reference
# curl https://api.nowgo.io/v0/shifts/ext-ref/shift-99 \
-X PATCH \
-u :{auth_token} \
-d {body}
Resources can be retrieved or modified using their external references, in addition to accessing them using their ID.
When accessing a created resource in this way, the external reference should be prefixed with /ext-ref/
, as outlined in the examples.
Entity versions
Example object
{
"id": "123545gDVE4",
"version": 7
}
Failing request
> PATCH /stops/123545gDVE4
> Nowgo-If-Match: 6
< 412 Precondition Failed
Successful request
> PATCH /stops/123545gDVE4
> Nowgo-If-Match: 7
< 200 Ok
Sometimes when returning a response, the NowGo API will include a version number for an object. This can be used to safely make changes to an object and avoid the lost update problem.
If you include the header Nowgo-If-Match
in a request to update an entity, and the current version of the object does not match the version passed in the header, the API will respond with 412 Precondition Failed
.
Clients should never include the version
field in the body of an object in a request. If it is included, it will be silently ignored.
Shifts
The shift object
You can read more about shifts in Key Concepts.
Example Object
{
"id": "1e0e27a4-0956-4fbc-b594-d82867a5ac7e",
"ext_ref": "2017VR882D",
"channel_id": "4414",
"time_window_start": "2017-02-13T20:46:30Z",
"time_window_end": "2017-02-13T20:50:30Z",
"driver_id": "2",
"driver": {},
"complete": [
{
"stop_id": "43b6fb8a-854c-4a46-8df5-b1f1194ab009",
"most_recent_completion": "2017-01-01T14:00:32Z",
"most_recent_is_success": true,
"completion_ids": [
"827492"
]
}
],
"planned_events": [
{
"stop_id": "43b6fb8a-854c-4a46-8df5-b1f1194ab010",
"ext_ref": "stop123",
"expected_start": "2024-01-01T14:00:32Z",
"locked": false,
"locked_by_driver": false
},
{
"break_id": "43b6fb8a-854c-4a46-8df5-b1f1194ab010",
"ext_ref": "break123",
"expected_start": "2024-01-01T14:00:32Z",
"locked": false,
"locked_by_driver": false
},
],
"jobs": [{}],
"vehicle_type_id": "44131",
"vehicle_type_ext_ref": "small-truck",
"vehicle_id": "157",
"vehicle_ext_ref": "truck-B7V-A6M",
"type": null,
"data": null,
"start_location_latitude": -33.9181216,
"start_location_longitude": 151.1470805,
"start_location_address": "466 Illawarra Rd, Dulwich Hill NSW 2203",
"end_location_latitude": -33.873828,
"end_location_longitude": 151.1920326,
"end_location_address": "Bank St & Pyrmont Bridge Road, Sydney NSW 2009",
"allow_driver_edit_stop": true,
"frozen": true,
"name": "twilight",
"allow_driver_self_assign": true
}
Attributes | ||
---|---|---|
id | string | |
ext_ref | string | External reference for the shift. |
channel_id | string | Id of the channel that currently contains the shift. |
time_window_start | timestamp | The earliest time that work can be completed in the shift. |
time_window_end | timestamp | The latest time that work can be completed in the shift. |
Under certain user-controlled scenarios, work may be scheduled outside time windows. This includes when operating with relaxed time constraints. | ||
driver_id | string | Id of the driver assigned to this shift. |
driver | driver object | Driver currently assigned to this shift. |
complete | Stops that have been completed within this shift. | |
stop_id | string | Id of the completed stop. |
most_recent_completion | timestamp | Time of the most recent completion for the given stop. |
most_recent_is_success | boolean | If the most recent completion was successful. |
completion_ids | string list | All ids of completions of the stop. |
planned_events | Events that are planned within the shift. These can be stops or breaks. | |
stop_id | string | ID of the planned stop, for stop events. |
break_id | string | ID of the planned break, for break events. |
expected_start | string | Expected start time of the planned event. |
locked | boolean | true if the stop is locked in position, false otherwise. |
locked_by_driver | boolean | true if the stop is locked in position by the driver, false otherwise. |
jobs | job object list | List of jobs that have stops planned in this shift. |
vehicle_type_id | string | Id of the vehicle type attached to this shift. |
vehicle_type_ext_ref | string | External reference of the vehicle type attached to this shift. |
vehicle_id | string | Id of the vehicle attached to this shift. |
vehicle_ext_ref | string | External reference of the vehicle attached to this shift. |
type | string | Type of this shift. |
data | json | Custom data attached to this shift. |
start_location_latitude | double | Latitude from which the driver starts driving, not before time_window_start. |
start_location_longitude | double | Longitude from which the driver starts driving, not before time_window_start. |
start_location_address | string | Location from which the driver starts driving. This field is only used for display purposes. |
end_location_latitude | double | Latitude at which the driver must finish driving. |
end_location_longitude | double | Longitude at which the driver must finish driving. |
end_location_address | string | Location at which the driver must finish driving. This field is only used for display purposes. |
allow_driver_edit_stop | boolean | If true, drivers are able to edit stops in the shift via the driver app. |
frozen | boolean | If true, the system will not make changes to this shift. Solves will not assign or remove stops, and assigned stops will not be reordered. |
name | string | Name of the shift. |
allow_driver_self_assign | boolean | If true, makes the shift eligible for self-assignment (if available). |
Create a shift
Example Request
# curl https://api.nowgo.io/v0/shifts \
-u :{auth_token} \
-d {body}
Example Request (in plan)
# curl https://api.nowgo.io/v0/plans/{plan_id}/shifts \
-u :{auth_token} \
-d {body}
Example Body
{
"ext_ref": "2017VR882D",
"channel_ext_ref": "61",
"time_window_start": "2016-04-01T13:15:00+10:00",
"time_window_end": "2016-04-01T17:00:00+10:00",
"driver_ext_ref": "959",
"stop_ids": [
"929",
"142",
"991"
],
"vehicle_type_ext_ref": "small-van",
"vehicle_id": "124",
"type": "afternoon-run",
"data": {
"depot_warning": "All drivers must wear safety gear on site."
},
"start_location_latitude": -33.9181216,
"start_location_longitude": 151.1470805,
"start_location_address": "466 Illawarra Rd, Dulwich Hill NSW 2203",
"end_location_latitude": -33.873828,
"end_location_longitude": 151.1920326,
"end_location_address": "Bank St & Pyrmont Bridge Road, Sydney NSW 2009",
"allow_driver_edit_stop": true,
"frozen": false,
"name": "twilight",
"allow_driver_self_assign": true
}
Body Parameters | ||
---|---|---|
ext_ref | string, optional | External reference for the shift. |
channel_id | string, optional | Id of the channel in which to create this shift. |
channel_ext_ref | string, optional | External reference of the channel in which to create this shift. |
Only one of channel_id and channel_ext_ref should be supplied. If both are supplied, the value of channel_id will be used. If neither is supplied, the shift will be created in your organisation's default channel. |
||
time_window_start | timestamp | The time the shift should be started. |
time_window_end | timestamp | The time the shift should end. |
Under certain user-controlled scenarios, work may be scheduled outside time windows. This includes when operating with relaxed time constraints. | ||
driver_id | string | Id of the driver to assign to the shift. |
driver_ext_ref | string | External reference of the driver to assign to the shift. |
Only one of driver_id and driver_ext_ref should be supplied. If both are supplied, the value of driver_id will be used. |
||
stop_ids | string list, optional | Ids of any stops to be assigned to this shift. If some of the stops are already complete, those stops will be ignored. If some of the stops are already assigned to a different shift, those stops will be removed and assigned to this shift. |
vehicle_type_id | string, optional | Id of the vehicle type to attach to this shift. |
vehicle_type_ext_ref | string, optional | External reference of the vehicle type to attach to this shift. |
vehicle_id | string | Id of the vehicle attached to this shift. |
vehicle_ext_ref | string | External reference of the vehicle attached to this shift. |
type | string, optional | Optional type of this shift. Does not affect behavior, at present. |
data | json, optional | Custom data to attach to this shift. |
start_location_latitude | double, optional | Latitude from which the driver starts driving, not before time_window_start. |
start_location_longitude | double, optional | Longitude from which the driver starts driving, not before time_window_start. |
start_location_address | string, optional | Location from which the driver starts driving. This field is only used for display purposes. |
end_location_latitude | double, optional | Latitude at which the driver must finish driving. |
end_location_longitude | double, optional | Longitude at which the driver must finish driving. |
end_location_address | string, optional | Location at which the driver must finish driving. This field is only used for display purposes. |
allow_driver_edit_stop | boolean, optional | If true, drivers are able to edit stops in the shift via the driver app. |
frozen | boolean, optional | If true, the system will not make changes to this shift. Solves will not assign or remove stops, and assigned stops will not be reordered. |
name | string | Name of the shift. |
allow_driver_self_assign | boolean, optional | If true, makes the shift eligible for self-assignment (if available). |
Response
Returns a shift object if creation was successful. Returns an error if something goes wrong.
Retrieve a shift
Example Request (using id)
# curl https://api.nowgo.io/v0/shifts/{id} \
-u :{auth_token}
Example Request (using external reference)
# curl https://api.nowgo.io/v0/shifts/ext-ref/{ext_ref} \
-u :{auth_token}
Shifts can be retrieved using their id or external reference.
Path Parameters | ||
---|---|---|
id | string | The id of the shift to be retrieved. |
ext_ref | string | The external reference of the shift to be retrieved. |
Response
Returns a shift object if the given identifier is valid, and returns an error otherwise.
Update a shift
Example Request (using id)
# curl https://api.nowgo.io/v0/shifts/{id} \
-X PATCH \
-u :{auth_token} \
-d {body}
Example Request (using external reference)
# curl https://api.nowgo.io/v0/shifts/ext-ref/{ext_ref} \
-X PATCH \
-u :{auth_token} \
-d {body}
Example Body
{
"time_window_start": "2016-04-01T13:15:00+10:00",
"time_window_end": "2016-04-01T17:00:00+10:00",
"stop_ids": [
"929",
"142",
"991"
],
"vehicle_type_ext_ref": "large-van",
"vehicle_ext_ref": "van-B51-M42",
"type": null,
"data": {
"depot_warning": "All drivers must wear safety gear on site."
},
"start_location_latitude": -33.9181216,
"start_location_longitude": 151.1470805,
"start_location_address": "466 Illawarra Rd, Dulwich Hill NSW 2203",
"end_location_latitude": -33.873828,
"end_location_longitude": 151.1920326,
"end_location_address": "Bank St & Pyrmont Bridge Road, Sydney NSW 2009",
"allow_driver_edit_stop": true,
"frozen": true,
"name": "twilight",
"allow_driver_self_assign": true
}
Applies an update to the given shift. Any parameters set to null
in the request will be cleared if valid. Any parameters not passed in the request will remain unchanged. You can read more about the semantics of PATCH
in updating resources.
Path Parameters | ||
---|---|---|
id | string | The id of the shift being modified. |
ext_ref | string | The external reference of the shift being modified. |
Body Parameters | ||
---|---|---|
time_window_start | timestamp | The time the shift should be started. |
time_window_end | timestamp | The time the shift should end. |
Under certain user-controlled scenarios, work may be scheduled outside time windows. This includes when operating with relaxed time constraints. | ||
driver_id | string | Id of the driver to assign to the shift. |
driver_ext_ref | string | External reference of the driver to assign to the shift. |
Only one of driver_id and driver_ext_ref should be supplied. If both are supplied, the value of driver_id will be used. |
||
stop_ids | string list, optional | Ids of any stops to be assigned to this shift. If some of the stops are already complete, those stops will be ignored. If some of the stops are already assigned to a different shift, those stops will be removed and assigned to this shift. |
vehicle_type_id | string, optional | Id of the vehicle type to attach to this shift. |
vehicle_type_ext_ref | string, optional | External reference of the vehicle type to attach to this shift. |
vehicle_id | string | Id of the vehicle attached to this shift. |
vehicle_ext_ref | string | External reference of the vehicle attached to this shift. |
type | string, optional | Optional type of this shift. Does not affect behavior, at present. |
data | json, optional | Custom data to attach to this shift. |
start_location_latitude | double, optional | Latitude from which the driver starts driving, not before time_window_start. |
start_location_longitude | double, optional | Longitude from which the driver starts driving, not before time_window_start. |
start_location_address | string, optional | Location from which the driver starts driving. This field is only used for display purposes. |
end_location_latitude | double, optional | Latitude at which the driver must finish driving. |
end_location_longitude | double, optional | Longitude at which the driver must finish driving. |
end_location_address | string, optional | Location at which the driver must finish driving. This field is only used for display purposes. |
allow_driver_edit_stop | boolean, optional | If true, drivers are able to edit stops in the shift via the driver app. |
frozen | boolean, optional | If true, the system will not make changes to this shift. Solves will not assign or remove stops, and assigned stops will not be reordered. |
name | string | Name of the shift. |
allow_driver_self_assign | boolean, optional | If true, makes the shift eligible for self-assignment (if available). |
Response
Returns a shift object if the update was successful. Returns an error if something goes wrong.
Update the stops in a shift
The behavior of this request varies depending on the request method used. If the method is PUT
, the shift's planned stops will be replaced with the given list. If POST
, the given stops will be appended to the shift's planned stops.
Example request (using id)
# curl https://api.nowgo.io/v0/shifts/{id}/stops \
-X PUT \
-u :{auth_token} \
-d {body}
Example request (using external reference)
# curl https://api.nowgo.io/v0/shifts/ext-ref/{ext_ref}/stops \
-X PUT \
-u :{auth_token} \
-d {body}
Example body
[
"334145",
"449274"
]
Path Parameters | |
---|---|
id | string |
ext_ref | string |
Body Parameters | |
---|---|
string list | Ids of stops to add to the shift. If some of the stops are already complete, those stops will be ignored. If some of the stops are already assigned to a different shift, those stops will be removed and assigned to this shift. If some of the stops are already assigned to this shift, and the request method is POST , they will be removed from their current position and put in their updated position from the request. |
Unassign the stops in a shift
Example request (using id)
# curl https://api.nowgo.io/v0/shifts/{shift_id}/stops/unassign \
-u :{auth_token} \
-d {body}
Example request (using external reference)
# curl https://api.nowgo.io/v0/shifts/ext-ref/{shift_ext_ref}/stops/unassign \
-u :{auth_token} \
-d {body}
Example body
[
{
"id": "1e0e27a4-0956-4fbc-b594-d82867a5ac7e"
},
{
"ext_ref": "other_stop"
}
]
Stops which have been planned in a shift can be unassigned using this endpoint by supplying a list of stop ids or external references.
Path Parameters | ||
---|---|---|
shift_id | string | The id of the shift being modified. |
shift_ext_ref | string | The external reference of the shift being modified. |
Body Parameters | ||
---|---|---|
id | string | The id of the stop to be unassigned. |
ext_ref | string | The external reference of the stop to be unassigned. |
Response
Returns a list of ids of stops which were unassigned from this shift. This request will fail if any supplied ids or external references are invalid or not assigned to this shift.
Delete a shift
Example request (using id)
# curl https://api.nowgo.io/v0/shifts/{shift_id} \
-u :{auth_token} \
-X DELETE
Example request (using external reference)
# curl https://api.nowgo.io/v0/shifts/ext-ref/{shift_ext_ref} \
-u :{auth_token} \
-X DELETE
Deletes a shift. Any stops assigned to the shift will become unassigned.
When a shift is deleted via the API, the shift's external reference is cleared and can be used again elsewhere.
Path Parameters | ||
---|---|---|
shift_id | string | The id of the shift being deleted. |
shift_ext_ref | string | The external reference of the shift being deleted. |
Jobs
The job object
You can read more about jobs in Key Concepts. Vehicle requirements are described in more detail in Further Concepts. Annotations are described in more detail in the annotations section. Priorities are described in more detail in the priorities section.
Example Response
{
"id": "5f125674-f403-4fe4-803d-f1dd56ce8267",
"ext_ref": "2017-33232",
"channel_id": "4414",
"stops": [{}],
"priority_weighting": 1.1,
"priority_id": "1",
"priority_ext_ref": "high",
"allowed_driver_ids": [
"434"
],
"allowed_shifts": [
{
"id": "22313"
},
{
"ext_ref": "shift1"
}
],
"allowed_vehicle_types": [
{
"vehicle_type_id": "414"
},
{
"vehicle_type_ext_ref": "red_bikes"
},
{
"vehicle_type_id": "416",
"vehicle_type_ext_ref": "blue_cars"
}
],
"vehicle_type_preferences": [
{
"vehicle_type_id": "414",
"preference": "positive"
},
{
"vehicle_type_ext_ref": "blue_cars",
"preference": "negative"
}
],
"allowed_vehicles": [
{
"vehicle_id": "91"
},
{
"vehicle_ext_ref": "car_14"
},
{
"vehicle_id": "93",
"vehicle_ext_ref": "car_15"
}
],
"vehicle_preferences": [
{
"vehicle_id": "92",
"preference": "positive"
},
{
"vehicle_ext_ref": "car_14",
"preference": "negative"
}
],
"vehicle_requirements": [
{
"id": "43",
"ext_ref": "refrigerated",
"pass_if_absent": true,
"expected": false
},
{
"id": "2854",
"pass_if_absent": false,
"min": 12
},
{
"id": "9464",
"pass_if_absent": true,
"max": 100
},
{
"id": "129",
"pass_if_absent": true,
"min": 10,
"max": 20
}
],
"active_outbound_delegation_request": {
"delegated_channel": {
"id": "123",
"ext_ref": null,
"display_name": "Acme Third Party P/L"
},
"reason": "Not enough capacity",
"accepted": true
},
"type": null,
"data": null
}
Attributes | ||
---|---|---|
id | string | |
ext_ref | string | External reference for the job. |
channel_id | string | Id of the channel that currently contains the job. |
stops | stop object list | Stops contained by the job. |
priority_weighting | double | Explicit priority value set for the job. |
priority_id | Id of the priority assigned to this job. | |
priority_ext_ref | External reference of the priority assigned to this job. | |
allowed_driver_ids | string list | Ids of drivers that are allowed to complete this job. If empty, any driver is eligible to be scheduled stops in this job. |
allowed_shifts | Ids and/or external references of shifts which are allowed to complete this job. If none are specified, using either ids or ext_ref s, all shifts will be considered compatible. |
|
id | string | Id of the shift. |
ext_ref | string | External reference of the shift. |
allowed_vehicle_types | Ids and/or external references of vehicle types which are allowed to complete this job. If none are specified, using either ids or ext_ref s, all vehicle types will be considered compatible. |
|
vehicle_type_id | string | Id of the vehicle type. |
vehicle_type_ext_ref | string | External reference of the vehicle type. |
allowed_vehicle_type_ids | string list | (Deprecated, use the above parameter). Ids of vehicle types that are able to complete stops contained by the job. |
vehicle_type_preferences | Positive or negative adjustments to the desirability of specific vehicle types. For example, this could be used to prefer the use of motorbikes over cars in urban environments. If no specific preferences are provided, all vehicles are considered equally desirable. | |
vehicle_type_id | string | Id of the vehicle type. |
vehicle_type_ext_ref | string | External reference of the vehicle type. |
preference | string | Preference for the vehicle type, either "positive" or "negative". |
allowed_vehicles | Ids and/or external references of specific vehicles which are allowed to complete this job. If none are specified, all vehicles matching the allowed vehicle types will be permitted. | |
vehicle_id | string | Id of the vehicle. |
vehicle_ext_ref | string | External reference of the vehicle. |
vehicle_preferences | Positive or negative adjustments to the desirability of specific vehicles. For example, this could be used to prefer the use of a specific kind of van over other vans. If no specific preferences are provided, all allowed vehicles are considered equally desirable. | |
vehicle_id | string | Id of the vehicle. |
vehicle_ext_ref | string | External reference of the vehicle. |
preference | string | Preference for the vehicle, either "positive" or "negative". |
vehicle_requirements | Any vehicle type or vehicle will be considered for this job only if it meets all the job's requirements. If no specific requirements are provided, all vehicles will pass this test. | |
id | string | Id of the attribute this requirement references. |
ext_ref | string | External reference of the attribute this requirement references. |
pass_if_absent | boolean | If 'true', then vehicles that do not have a value for the referenced attribute will be considered to pass the requirement. If false, vehicles lacking a value for the referenced attribute will fail the requirement (and hence not be considered for the job). |
min | long | A vehicle's value for the referenced attribute must be at least 'min', else it will not be considered for the job. Only applicable to numeric attributes. Can be specified by itself (greater-than requirement) or together with 'max' (between requirement). |
max | long | A vehicle's value for the referenced attribute must be at least 'min', else it will not be considered for the job. Only applicable to numeric attributes. Can be specified by itself (less-than requirement) or together with 'min' (between requirement). |
expected | boolean | A vehicle's value for the referenced attribute must equal 'expected', else it will not be considered for the job. Only applicable to boolean attributes. |
active_outbound_delegation_request | If the job is delegated or pending delegation, this is set and contains information about the delegation. Otherwise, this is null. | |
delegated_channel | Details about the delegated channel to which the job is being delegated. | |
id | string | Id of the delegated channel. |
ext_ref | string | External reference of the delegated channel. |
display_name | string | Human-readable name of the delegated channel. |
reason | string | User-specified reason for delegating the job. |
accepted | boolean | If true, the job has been accepted by the delegated channel, either explicitly or automatically. If null, the delegation request is still pending a response from the delegated channel. |
type | string | Type of this job. |
data | json | Custom data attached to this job. |
Create a job
Example Request
# curl https://api.nowgo.io/v0/jobs \
-u :{auth_token} \
-d {body}
Example Request (in plan)
# curl https://api.nowgo.io/v0/plans/{plan_id}/jobs \
-u :{auth_token} \
-d {body}
Example Body
{
"ext_ref": "2017-33232",
"channel_ext_ref": "61",
"stops": [
{
"ext_ref": "2017-33232-1",
"time_window_start": "2016-04-01T13:20:00+10:00",
"time_window_end": "2016-04-01T14:00:00+10:00",
"service_time": 180,
"location": {
"address": "483 George St, Sydney NSW 2000",
"latitude": -33.8727137,
"longitude": 151.2059311
},
"type": "pickup"
},
{
"ext_ref": "2017-33232-2",
"time_window_start": "2016-04-01T13:20:00+10:00",
"time_window_end": "2016-04-01T14:00:00+10:00",
"service_time": 180,
"location": {
"id": "141",
"ext_ref": "warehouse_21"
},
"type": "dropoff"
}
],
"priority_weighting": 1.1,
"priority_ext_ref": "high",
"allowed_driver_ids": [
"434"
],
"allowed_shifts": [
{
"ext_ref": "shift1"
}
],
"allowed_vehicle_types": [
{
"vehicle_type_id": "414"
},
{
"vehicle_type_ext_ref": "red_bikes"
},
{
"vehicle_type_id": "414",
"vehicle_type_ext_ref": "blue_cars"
}
],
"vehicle_type_preferences": [
{
"vehicle_type_id": "414",
"preference": "positive"
},
{
"vehicle_type_ext_ref": "blue_cars",
"preference": "negative"
}
],
"allowed_vehicles": [
{
"vehicle_id": "91"
},
{
"vehicle_ext_ref": "car_14"
},
{
"vehicle_id": "93",
"vehicle_ext_ref": "car_15"
}
],
"vehicle_preferences": [
{
"vehicle_id": "92",
"preference": "positive"
},
{
"vehicle_ext_ref": "car_14",
"preference": "negative"
}
],
"vehicle_requirements": [
{
"id": "43",
"ext_ref": "refrigerated",
"pass_if_absent": true,
"expected": false
},
{
"id": "9464",
"pass_if_absent": true,
"max": 100
}
],
"type": "afternoon-pickup",
"data": {
"depot-safety": "Drivers to wear high-vis on site at all times."
},
"start_comms_sessions": [
{
"comms_plan_id": "123",
},
{
"comms_plan_ext_ref": "standard-comms",
}
],
"initial_assignment": {
"shift_id": "11a0a9d5-7e6c-484d-b273-95a87c0b49f3",
"shift_ext_ref": "shift-123"
}
}
This operation is available in plans.
Body Parameters | ||
---|---|---|
ext_ref | string, optional | External reference for the job. |
channel_id | string, optional | Id of the channel in which to create this job. |
channel_ext_ref | string, optional | External reference of the channel in which to create this job. |
Only one of channel_id and channel_ext_ref should be supplied. If both are supplied, the value of channel_id will be used. If neither is supplied, the job will be created in your organisation's default channel. |
||
stops | stop object list, optional | Stops contained within the job. Stops within the same job will be completed in order. For more information on stop parameters, see the stop documentation |
priority_weighting | double, optional | Explicit priority value to set for the job. |
priority_id | string, optional | Id of the priority to set for the job. |
priority_ext_ref | string, optional | External reference of the priority to set for the job. |
Only one of priority_id and priority_ext_ref should be supplied. If both are supplied, the value of priority_id will be used. If neither is supplied, the job will use the organisation's default priority, if configured. |
||
allowed_driver_ids | string list, optional | Ids of drivers that are allowed to complete this job. If this and allowed_driver_ext_refs are empty, any driver is eligible to be scheduled for this job. |
allowed_driver_ext_refs | string list, optional | External references of drivers that are allowed to complete this job. If this and allowed_driver_ids are empty, any driver is eligible to be scheduled for this job. |
allowed_shifts | optional | Ids and/or external references of shifts which are allowed to complete this job. If none are specified, using either ids or ext_ref s, all shifts will be considered compatible. At present, only a single compatible shift can be specified in this parameter. |
id | string | Id of the shift. |
ext_ref | string | External reference of the shift. |
allowed_vehicle_types | optional | Ids and/or external references of vehicle types which are allowed to complete this job. If none are specified, using either ids or ext_ref s, all vehicle types will be considered compatible. |
vehicle_type_id | string | Id of the vehicle type. |
vehicle_type_ext_ref | string | External reference of the vehicle type. |
allowed_vehicle_type_ids | string list, optional | (Deprecated, use the above parameter). Ids of vehicle types that are able to complete stops contained by the job. |
vehicle_type_preferences | optional | Positive or negative adjustments to the desirability of specific vehicle types. For example, this could be used to prefer the use of motorbikes over cars in urban environments. If no specific preferences are provided, all vehicles are considered equally desirable. |
vehicle_type_id | string | Id of the vehicle type. |
vehicle_type_ext_ref | string | External reference of the vehicle type. |
preference | string | Preference for the vehicle type, either "positive" or "negative". |
allowed_vehicles | optional | Ids and/or external references of specific vehicles which are allowed to complete this job. If none are specified, all vehicles matching the allowed vehicle types will be permitted. |
vehicle_id | string | Id of the vehicle. |
vehicle_ext_ref | string | External reference of the vehicle. |
vehicle_preferences | optional | Positive or negative adjustments to the desirability of specific vehicles. For example, this could be used to prefer the use of a specific kind of van over other vans. If no specific preferences are provided, all allowed vehicles are considered equally desirable. |
vehicle_id | string | Id of the vehicle. |
vehicle_ext_ref | string | External reference of the vehicle. |
preference | string | Preference for the vehicle, either "positive" or "negative". |
vehicle_requirements | optional | Any vehicle type or vehicle will be considered for this job only if it meets all the job's requirements. If no specific requirements are provided, all vehicles will pass this test. |
id | string | Id of the attribute this requirement references. |
ext_ref | string | External reference of the attribute this requirement references. |
pass_if_absent | boolean | If 'true', then vehicles that do not have a value for the referenced attribute will be considered to pass the requirement. If false, vehicles lacking a value for the referenced attribute will fail the requirement (and hence not be considered for the job). |
min | long | A vehicle's value for the referenced attribute must be at least 'min', else it will not be considered for the job. Only applicable to numeric attributes. |
max | long | A vehicle's value for the referenced attribute must be at least 'min', else it will not be considered for the job. Only applicable to numeric attributes. |
expected | boolean | A vehicle's value for the referenced attribute must equal 'expected', else it will not be considered for the job. Only applicable to boolean attributes. |
type | string, optional | Optional type of this job. Does not affect behavior, at present. |
data | json, optional | Custom data to attach to this job. |
start_comms_sessions | optional | Explicitly begins communication sessions for the created job. |
comms_plan_id | string, optional | Id of the comms plan for which to start a comms session. |
comms_plan_ext_ref | string, optional | External reference of the comms plan for which to start a comms session. |
initial_assignment | optional | If present, assigns the newly created job to a shift. |
shift_id | string, optional | Id of the shift to which the stop's jobs will be assigned. |
shift_ext_ref | string, optional | External reference of the shift to which the stop's jobs will be assigned. |
Response
Returns a job object if creation was successful. Returns an error if something goes wrong.
Retrieve a job
Example Request (using job id)
# curl https://api.nowgo.io/v0/jobs/{job_id} \
-u :{auth_token}
Example Request (using job external reference)
# curl https://api.nowgo.io/v0/jobs/ext-ref/{job_ext_ref} \
-u :{auth_token}
Example Request (using stop id)
# curl https://api.nowgo.io/v0/stops/{stop_id}/jobs \
-u :{auth_token}
Example Request (using stop external reference)
# curl https://api.nowgo.io/v0/stops/ext-ref/{stop_ext_ref}/jobs \
-u :{auth_token}
Example Request (in plan using job id)
# curl https://api.nowgo.io/v0/plans/{plan_id}/jobs/{job_id} \
-u :{auth_token}
Example Request (in plan using job external reference)
# curl https://api.nowgo.io/v0/plans/{plan_id}/jobs/ext-ref/{job_ext_ref} \
-u :{auth_token}
Job objects can be retrieved using a job id or job external reference. They can also be retrieved using a stop id or stop external reference.
This operation is available in plans.
Path Parameters | ||
---|---|---|
job_id | string | The id of the job to be retrieved. |
job_ext_ref | string | The external reference of the job to be retrieved. |
stop_id | string | The id of the stop attached to the job of interest. |
stop_ext_ref | string | The external reference attached to the job of interest. |
Response
Returns a job if the given identifier is valid, and returns an error otherwise.
Update a job
Example Request (using job id)
# curl https://api.nowgo.io/v0/jobs/{job_id} \
-X PATCH \
-u :{auth_token} \
-d {body}
Example Request (using external reference)
# curl https://api.nowgo.io/v0/jobs/ext-ref/{ext_ref} \
-X PATCH \
-u :{auth_token} \
-d {body}
Example Request (in plan using id)
# curl https://api.nowgo.io/v0/plans/{plan_id}/jobs/{job_id} \
-X PATCH \
-u :{auth_token} \
-d {body}
Example Request (in plan using external reference)
# curl https://api.nowgo.io/v0/plans/{plan_id}/jobs/ext-ref/{ext_ref} \
-X PATCH \
-u :{auth_token} \
-d {body}
Example Body
{
"priority_weighting": 1.4,
"priority_id": "1",
"priority_ext_ref": "high",
"allowed_driver_ids": [
"434",
"552"
],
"allowed_shifts": [
{
"ext_ref": "shift1"
}
],
"allowed_vehicle_types": [
{
"vehicle_type_id": "414"
},
{
"vehicle_type_id": "419"
}
],
"vehicle_type_preferences": [
{
"vehicle_type_id": "414",
"preference": "positive"
}
],
"allowed_vehicles": [
{
"vehicle_id": "103",
"vehicle_ext_ref": "truck_11"
}
],
"vehicle_requirements": [
{
"id": "9464",
"ext_ref": "height",
"pass_if_absent": true,
"max": 100
}
],
"type": "priority-delivery",
"data": {
"customer-relations": "Remember to wish the customer a lovely day."
}
}
Applies an update to the given job. Any parameters set to null
in the request will be cleared if valid. Any parameters not passed in the request will remain unchanged. You can read more about the semantics of PATCH
in updating resources.
Note that the deprecated allowed_vehicle_type_ids
and allowed_vehicle_types
field fulfil the same purpose.
If either is used, then all existing values will be replaced by the new values
This operation is available in plans.
Path Parameters | ||
---|---|---|
id | string | The id of the job to be updated. |
ext_ref | string | The external reference of the job to be updated. |
Body Parameters | ||
---|---|---|
priority_weighting | double, optional | Explicit priority value to set for the job. |
priority_id | string, optional | Id of the priority to set for the job. |
priority_ext_ref | string, optional | External reference of the priority to set for the job. |
Only one of priority_id and priority_ext_ref should be supplied. If both are supplied, the value of priority_id will be used. If neither is supplied, the job will use the organisation's default priority, if configured. |
||
allowed_driver_ids | string list, optional | Ids of drivers that are allowed to complete this job. If this and allowed_driver_ext_refs are empty, any driver is eligible to be scheduled for this job. If the job is already assigned to a shift, changing the allowed drivers will not automatically reassign it. |
allowed_driver_ext_refs | string list, optional | External references of drivers that are allowed to complete this job. If this and allowed_driver_ids are empty, any driver is eligible to be scheduled for this job. If the job is already assigned to a shift, changing the allowed drivers will not automatically reassign it. |
allowed_shifts | Ids and/or external references of shifts which are allowed to complete this job. If none are specified, using either ids or ext_ref s, all shifts will be considered compatible. At present, only a single compatible shift can be specified in this parameter. If the job is already assigned to a shift, changing the allowed shifts will not automatically reassign it. |
|
id | string | Id of the shift. |
ext_ref | string | External reference of the shift. |
allowed_vehicle_types | Ids and/or external references of vehicle types which are allowed to complete this job. If none are specified, using either ids or ext_ref s, all vehicle types will be considered compatible. If the job is already assigned to a shift, changing the allowed vehicle types will not automatically reassign it. |
|
vehicle_type_id | string | Id of the vehicle type. |
vehicle_type_ext_ref | string | External reference of the vehicle type. |
allowed_vehicle_type_ids | string list | (Deprecated, use the above parameter). Ids of vehicle types that are able to complete stops contained by the job. If the job is already assigned to a shift, changing the allowed vehicle types will not automatically reassign it. |
vehicle_type_preferences | Positive or negative adjustments to the desirability of specific vehicle types. For example, this could be used to prefer the use of motorbikes over cars in urban environments. If no specific preferences are provided, all vehicles are considered equally desirable. | |
vehicle_type_id | string | Id of the vehicle type. |
vehicle_type_ext_ref | string | External reference of the vehicle type. |
preference | string | Preference for the vehicle type, either "positive" or "negative". |
allowed_vehicles | Ids and/or external references of specific vehicles which are allowed to complete this job. If none are specified, all vehicles matching the allowed vehicle types will be permitted. If the job is already assigned to a shift, changing the allowed vehicles will not automatically reassign it. | |
vehicle_id | string | Id of the vehicle. |
vehicle_ext_ref | string | External reference of the vehicle. |
vehicle_preferences | Positive or negative adjustments to the desirability of specific vehicles. For example, this could be used to prefer the use of a specific kind of van over other vans. If no specific preferences are provided, all allowed vehicles are considered equally desirable. | |
vehicle_id | string | Id of the vehicle. |
vehicle_ext_ref | string | External reference of the vehicle. |
preference | string | Preference for the vehicle, either "positive" or "negative". |
vehicle_requirements | Any vehicle type or vehicle will be considered for this job only if it meets all the job's requirements. If no specific requirements are provided, all vehicles will pass this test. | |
id | string | Id of the attribute this requirement references. |
ext_ref | string | External reference of the attribute this requirement references. |
pass_if_absent | boolean | If 'true', then vehicles that do not have a value for the referenced attribute will be considered to pass the requirement. If false, vehicles lacking a value for the referenced attribute will fail the requirement (and hence not be considered for the job). |
min | long | A vehicle's value for the referenced attribute must be at least 'min', else it will not be considered for the job. Only applicable to numeric attributes. |
max | long | A vehicle's value for the referenced attribute must be at least 'min', else it will not be considered for the job. Only applicable to numeric attributes. |
expected | boolean | A vehicle's value for the referenced attribute must equal 'expected', else it will not be considered for the job. Only applicable to boolean attributes. |
type | string, optional | Optional type of this job. Does not affect behavior, at present. |
data | json, optional | Custom data to attach to this job. |
Response
Returns a job object if the update was successful. Returns an error if something goes wrong.
Unassign a job
Example Request (using id)
# curl https://api.nowgo.io/v0/jobs/{job_id}/assignment \
-X DELETE \
-u :{auth_token}
Example Request (using external reference)
# curl https://api.nowgo.io/v0/jobs/ext-ref/{ext_ref}/assignment \
-X DELETE \
-u :{auth_token}
Example Request (in plan using job id)
# curl https://api.nowgo.io/v0/plans/{plan_id}/job/{job_id}/assignment \
-X DELETE \
-u :{auth_token}
Example Request (in plan using external reference)
# curl https://api.nowgo.io/v0/plans/{plan_id}/job/ext-ref/{ext_ref}/assignment \
-X DELETE \
-u :{auth_token}
Makes a job's stops unassigned. This will remove stops from any shift that they are assigned to.
This operation is available in plans.
Delete a job
Example Request (using id)
# curl https://api.nowgo.io/v0/jobs/{job_id} \
-X DELETE \
-u :{auth_token}
Example Request (using external reference)
# curl https://api.nowgo.io/v0/jobs/ext-ref/{ext_ref} \
-X DELETE \
-u :{auth_token}
Example Request (in plan using job id)
# curl https://api.nowgo.io/v0/plans/{plan_id}/job/{job_id} \
-X DELETE \
-u :{auth_token}
Example Request (in plan using external reference)
# curl https://api.nowgo.io/v0/plans/{plan_id}/job/ext-ref/{ext_ref} \
-X DELETE \
-u :{auth_token}
Deletes a job and all its stops. This operation is not reversible. Deleting a job will not delete completions for its stops. Jobs deleted this way will remain in unrefreshed plans.
This operation is available in plans. When a job in a plan is deleted, that job is removed from the plan but is not deleted from dispatch. Explicitly delete the job from dispatch if want it removed completely.
Annotations
Annotations can be recorded on Jobs. This allows drivers to attach information to jobs. This is described in detail in the annotations section.
Stops
The stop object
You can read more about stops in Key Concepts.
Example Object
{
"id": "e802d0be-46f9-4809-8ab4-cc30ab65ca54",
"ext_ref": "2017-33232-1",
"job_id": "e8fc77b5-650c-4e84-b7fa-4a338f7870a9",
"shift_id": "95c9ed20-df91-4770-a620-10200d965703",
"time_window_start": "2017-02-13T12:00:00Z",
"time_window_end": "2017-02-13T14:00:00Z",
"service_time": 240,
"location_time": 60,
"location": {
"address": "75 Bronte Rd",
"locality": "Bondi Junction",
"state": "NSW",
"postal_code": "2022",
"latitude": -33.8925275,
"longitude": 151.2492009,
"contact_name": "John Smith",
"contact_phone": "04--------",
"contact_email": "example@nowgo.io",
"business_name": "Example Industries"
},
"disposition": {
"sticky": true
},
"closed": false,
"visible_to_driver": true,
"capacity_costs": [
{
"capacity_id": "5525",
"capacity_ext_ref": "weight-kgs",
"cost": 30
}
],
"location_groups": [{}],
"type": "delivery",
"data": {
"atl": "Please leave package by the front gate."
},
"precursors": [
{
"precursor_id": "042fcc7b-a391-4935-b99b-c67c377d3a7d",
"same_start": false
}
],
"autocomplete_rule": {
"radius_metres": 400,
"trigger_type": "enter",
"can_complete_out_of_sequence": true
},
"target_article_ids": [
"182712871581385864",
"182713139773572237"
],
"action_id": 661,
"action_ext_ref": "pickup",
"delegation_pending": false,
"delegated": false
}
Attributes | ||
---|---|---|
id | string | |
ext_ref | string | External reference for the stop. |
job_id | string | Job that the stop is contained in. |
shift_id | string | Shift in which the stop is currently scheduled for completion. |
time_window_start | timestamp | The earliest time at which the stop should be completed. |
time_window_end | timestamp | The latest time at which the stop should be completed. |
service_time | integer | Time in seconds that the stop will take to complete. |
location_time | integer, optional | Time in seconds that visiting the stop will take prior to service time. Also see location groups |
location | ||
address | string | Human-readable address of the stop's location. This will be displayed to dispatchers and drivers. |
locality | string | Suburb, township, or city in which the stop is located. This will be displayed to dispatchers and drivers. |
state | string | State in which the stop is located. |
postal_code | string | Postal code of the location of the stop. |
latitude | double | Latitude of the stop. |
longitude | double | Longitude of the stop. |
contact_name | string | Name of the contact for the stop. |
contact_phone | string | Phone number of the contact for the stop. |
contact_email | string | Email address of the contact for the stop. |
business_name | string | Business name of the location at which the stop is located. |
disposition | Controls the solver behaviour of the stop. | |
sticky | boolean, optional | If true , once the stop is assigned to a shift the system will never automatically remove it from that shift. Defaults to false . |
closed | boolean | If true , the stop will not be scheduled for completion. This occurs when the stop is completed or cancelled. |
visible_to_driver | boolean | If true , drivers are able to see the stop as soon as it is scheduled in their shift. If false , the stop will not be visible until it is manually dispatched. Dispatching a stop will set this field to true . |
capacity_costs | capacity object list | Costs that this stop applies to capacities. |
capacity_id | string | Id of the capacity. |
capacity_ext_ref | string | External reference of the capacity. |
cost | integer | How much the stop decreases or increases the capacity by. Cost can be negative, for example, to represent dropping off heavy cargo. |
precursors | precursor object list | Stops that must be completed before this stop. |
precursor_id | string | Id of the precursor stop. |
same_start | boolean, optional | If true , this stop and the precursor stop will be routed so that they have approximately the same start times. |
location_groups | location group object list | Location groups that include the stop. |
type | string | Optional type of this stop. Does not affect behavior, at present. |
data | json | Custom data to attach to this stop. |
autocomplete_rule | Specifies the conditions under which the stop should automatically be completed. | |
radius_metres | integer | The radius of the autocomplete circle, measured in metres. |
trigger_type | string | Specifies the kind of movement that should cause the autocomplete to happen. Must be one of enter , leave or enter_or_leave . |
can_complete_out_of_sequence | boolean | If true , the stop will autocomplete regardless of position in the driver's shift. Defaults to false , so only the next stop in a shift will autocomplete. |
action_id | double, optional | Id of an associated action. If your organisation uses custom actions, they can be linked to a stop by provided an id here. |
action_ext_ref | double, optional | External reference of an associated action. If an action_id is also provided, that will be instead to find the action. |
target_article_ids | string list, optional | Ids of articles that are linked to this stop. |
delegation_pending | boolean | If true, there is a pending delegation request for this stop's job, and this stop is included in that request. |
delegated | boolean | If true , this stop is currently delegated. |
Locations in stops
Optionally, stops can have a location specified by id or external reference, which we refer to as a first-class location. If a location is specified in this way, the data from that location will be populated on the stop. The location's data acts like a template, which fills in the stop's data.
Updating a location's data will not change existing stops with that first-class location set. Existing stops will only be updated when their individual location data changes. This is so that, among other reasons, even if a location changes historical data remains consistent.
If you provide both a first-class location and extra location data, the extra data provided will override the data from the first-class location for the stop. For example, you could provide both a location.id
to attach a first-class location, but also an overriding latitude
and longitude
to direct a driver to the other end of a large block for a particular stop.
Adding stops to jobs
Example Request (using id)
# curl https://api.nowgo.io/v0/jobs/{job_id}/stops \
-u :{auth_token} \
-d {body}
Example Request (using external reference)
# curl https://api.nowgo.io/v0/jobs/ext-ref/{job_ext_ref}/stops \
-u :{auth_token} \
-d {body}
Example Request (in plan using id)
# curl https://api.nowgo.io/v0/plans/{plan_id}/jobs/{job_id}/stops \
-u :{auth_token} \
-d {body}
Example Request (in plan using external reference)
# curl https://api.nowgo.io/v0/plans/{plan_id}/jobs/ext-ref/{job_ext_ref}/stops \
-u :{auth_token} \
-d {body}
Example Body (using address)
{
"ext_ref": "2017-33232-1",
"time_window_start": "2017-02-13T12:00:00Z",
"time_window_end": "2017-02-13T14:00:00Z",
"service_time": 240,
"location": {
"address": "75 Bronte Rd",
"locality": "Bondi Junction",
"state": "NSW",
"postal_code": "2022",
"latitude": -33.8925275,
"longitude": 151.2492009,
"contact_name": "John Smith",
"contact_phone": "04--------",
"contact_email": "example@nowgo.io",
"business_name": "Example Industries"
},
"disposition": {
"sticky": true
},
"visible_to_driver": true,
"capacity_costs": [
{
"capacity_id": "5525",
"capacity_ext_ref": "weight-kgs",
"cost": 30
}
],
"location_groups": [
{
"id": "321"
}
],
"type": "delivery",
"data": {
"atl": "Please leave package by the front gate."
},
"precursors": [
{
"precursor_id": "042fcc7b-a391-4935-b99b-c67c377d3a7d",
"precursor_ext_ref": "2017-88787-2",
"same_start": false
}
],
"autocomplete_rule": {
"radius_metres": 200,
"trigger_type": "enter_or_leave",
"can_complete_out_of_sequence": true
},
"target_article_ids": [
"182712871581385864",
"182713139773572237"
]
}
Example Body (using location id and/or ext_ref)
{
"time_window_start": "2017-02-13T12:00:00Z",
"time_window_end": "2017-02-13T14:00:00Z",
"service_time": 240,
"location": {
"id": "41",
"ext_ref": "warehouse"
}
}
Stops always exist within a job. As such, there is no top-level endpoint to create a stop. Stops can be added to a job either when the job is created, or afterwards. When a stop is added to an existing job, the stop is appended to the end of the job's stops.
The location of a stop can be set using an address, as shown in the first example, or using an id or external reference of an existing location object, as shown in the second example.
If an id and/or external reference is supplied in the location parameter, the system will search for a location object matching those identifiers. If a matching location object is found, the stop will be created using that first-class location. Any additional location data in the request will override data from the first-class location. If both an id and an external reference for a location are supplied, the external reference will be ignored.
This operation is available in plans.
Body Parameters | ||
---|---|---|
job_id | string | The id of the job which is having stops added to it. |
job_ext_ref | string | External reference of the job which is having stops added to it. |
ext_ref | string, optional | External reference for the stop. |
time_window_start | timestamp | The earliest time at which the stop should be completed. |
time_window_end | timestamp | The latest time at which the stop should be completed. |
service_time | integer | Time in seconds that the stop will take to complete. |
location_time | integer, optional | Time in seconds that visiting the stop will take prior to service time. Also see location groups |
location | ||
id | string, optional | Id of an existing location object. |
ext_ref | string, optional | External reference of an existing location object. |
address | string, optional | Human-readable address of the stop's location. This will be displayed to dispatchers and drivers. |
locality | string, optional | Suburb, township, or city in which the stop is located. This will be displayed to dispatchers and drivers. |
state | string, optional | State in which the stop is located. Several forms of state are acceptable, for example, "NSW" and "New South Wales". No validity checking is performed on this field by the system. |
postal_code | string, optional | Postal code of the location of the stop. This is used as additional input when geocoding, and providing it greatly improves the accuracy of results. |
latitude | double, optional | Latitude of the stop. |
longitude | double, optional | Longitude of the stop. |
contact_name | string | Name of the contact for the stop. |
contact_phone | string | Phone number of the contact for the stop. |
contact_email | string | Email address of the contact for the stop. |
business_name | string, optional | Business name of the location at which the stop is located. |
If latitude and longitude are not provided, the system will attempt to geocode the given address and will use the best available result. At least one of address or latitude and longitude must be provided. |
||
geocode | boolean, optional | If true , the NowGo will always attempt to geocode the stop's address. If false , NowGo will never attempt to geocode. |
disposition | optional | Controls the solver behavior of the stop. |
sticky | boolean, optional | If true , once the stop is assigned to a shift the system will never automatically remove it from that shift. Defaults to false . |
visible_to_driver | boolean, optional | If true , drivers are able to see the stop as soon as it is scheduled in their shift. If false , the stop will not be visible until it is manually dispatched. Dispatching a stop will set this field to true . |
capacity_costs | capacity object list, optional | Costs that this stop applies to capacities. |
capacity_id | string, optional | Id of the capacity. |
capacity_ext_ref | string, optional | External reference of the capacity. |
cost | integer | How much the stop decreases or increases the capacity by. Cost can be negative, for example, to represent dropping off heavy cargo. |
precursors | precursor object list | Stops that must be completed before this stop. |
precursor_id | string | Id of the precursor stop. |
precursor_ext_ref | string | External reference of the precursor stop. |
same_start | boolean, optional | If true , this stop and the precursor stop will be routed so that they have approximately the same start times. |
location_groups | location group object list, optional | Location groups in which to place this stop. |
id | string | Id of the location group. |
ext_ref | string | External reference of the location group. |
At present, stops are limited to membership of a single location group. | ||
type | string, optional | Optional type of this stop. Does not affect behavior, at present. |
data | json, optional | Custom data to attach to this stop. |
autocomplete_rule | optional | Specifies the conditions under which the stop should automatically be completed. |
radius_metres | integer | The radius of the autocomplete circles, measured in metres. |
trigger_type | string | Specifies the kind of movement that should cause the autocomplete to happen. Must be one of enter , leave or enter_or_leave . |
can_complete_out_of_sequence | boolean | If true , the stop will autocomplete regardless of position in the driver's shift. Defaults to false , so only the next stop in a shift will autocomplete. |
target_article_ids | string list, optional | Ids of articles that are linked to this stop. |
Retrieve a stop
Example Request (using id)
# curl https://api.nowgo.io/v0/stops/{stop_id} \
-u :{auth_token}
Example Request (using external reference)
# curl https://api.nowgo.io/v0/stops/ext-ref/{ext_ref} \
-u :{auth_token}
Example Request (in plan using id)
# curl https://api.nowgo.io/v0/plans/{plan_id}/stops/{stop_id} \
-u :{auth_token}
Example Request (in plan using external reference)
# curl https://api.nowgo.io/v0/plans/{plan_id}/stops/ext-ref/{ext_ref} \
-u :{auth_token}
Stop objects can be retrieved using their ids or external references. This is an alternative method to retrieving the stop as part of the job object that the stop was attached to, as outlined in the jobs section.
This operation is available in plans.
Path Parameters | ||
---|---|---|
id | string | The id of the stop being retrieved. |
ext_ref | string | External reference of the stop being retrieved. |
Response
Returns a stop object if the request is valid.
Update a stop
Example Request (using id)
# curl https://api.nowgo.io/v0/stops/{stop_id} \
-X PATCH \
-u :{auth_token} \
-d {body}
Example Request (using external reference)
# curl https://api.nowgo.io/v0/stops/ext-ref/{ext_ref} \
-X PATCH \
-u :{auth_token} \
-d {body}
Example Request (using id)
# curl https://api.nowgo.io/v0/plans/{plan_id}/stops/{stop_id} \
-X PATCH \
-u :{auth_token} \
-d {body}
Example Request (using external reference)
# curl https://api.nowgo.io/v0/plans/{plan_id}/stops/ext-ref/{ext_ref} \
-X PATCH \
-u :{auth_token} \
-d {body}
Example Body
{
"time_window_start": "2017-02-13T12:00:00Z",
"time_window_end": "2017-02-13T14:00:00Z",
"service_time": 240,
"location": {
"address": "75 Bronte Rd",
"locality": "Bondi Junction",
"state": "NSW",
"postal_code": "2022",
"latitude": -33.8925275,
"longitude": 151.2492009,
"contact_name": "John Smith",
"contact_phone": "04--------",
"contact_email": "example@nowgo.io",
"business_name": "Example Industries"
},
"disposition": {
"sticky": true
},
"visible_to_driver": true,
"capacity_costs": [
{
"capacity_id": "5525",
"capacity_ext_ref": "weight-kgs",
"cost": 30
}
],
"location_groups": [
{
"id": "456"
}
],
"type": "delivery",
"data": {
"atl": "Please leave package by the front gate."
}
}
Applies an update to the given stop. Any parameters set to null
in the request will be cleared if valid. Any parameters not passed in the request will remain unchanged. You can read more about the semantics of PATCH
in updating resources.
This operation is available in plans.
Update requests can change stop location data, but cannot change the stop to a different location. Passing a change value in location.id
is an invalid request. Passing null
will clear the stop's location id.
Path Parameters | ||
---|---|---|
id | string | The id of the stop being modified. |
ext_ref | string | External reference of the stop being modified. |
Body Parameters | ||
---|---|---|
time_window_start | timestamp | The earliest time at which the stop should be completed. |
time_window_end | timestamp | The latest time at which the stop should be completed. |
service_time | integer | Time in seconds that the stop will take to complete. |
location_time | integer, optional | Time in seconds that visiting the stop will take prior to service time. Also see location groups |
location | ||
id | string, optional | NowGo id for the location. |
address | string, optional | Human-readable address of the stop's location. This will be displayed to dispatchers and drivers. |
locality | string, optional | Suburb, township, or city in which the stop is located. This will be displayed to dispatchers and drivers. |
state | string, optional | State in which the stop is located. Several forms of state are acceptable, for example, "NSW" and "New South Wales". No validity checking is performed on this field by the system. |
postal_code | string, optional | Postal code of the location of the stop. This is used as additional input when geocoding, and providing it greatly improves the accuracy of results. |
latitude | double, optional | Latitude of the stop. |
longitude | double, optional | Longitude of the stop. |
contact_name | string | Name of the contact for the stop. |
contact_phone | string | Phone number of the contact for the stop. |
contact_email | string | Email address of the contact for the stop. |
business_name | string, optional | Business name of the location at which the stop is located. |
If latitude and longitude are not provided, the system will attempt to geocode the given address data and will use the best available result. At least one of address or latitude and longitude must be provided. |
||
disposition | optional | Controls the solver behavior of the stop. |
sticky | boolean, optional | If true , once the stop is assigned to a shift the system will never automatically remove it from that shift. Defaults to false . |
visible_to_driver | boolean, optional | If true , drivers are able to see the stop as soon as it is scheduled in their shift. If false , the stop will not be visible until it is manually dispatched. Dispatching a stop will set this field to true . |
capacity_costs | capacity object list, optional | Costs that this stop applies to capacities. |
capacity_id | string, optional | Id of the capacity. |
capacity_ext_ref | string, optional | External reference of the capacity. |
cost | integer | How much the stop decreases or increases the capacity by. Cost can be negative, for example, to represent dropping off heavy cargo. |
precursors | precursor object list | Stops that must be completed before this stop. |
precursor_id | string | Id of the precursor stop. |
precursor_ext_ref | string | External reference of the precursor stop. |
same_start | boolean, optional | If true , this stop and the precursor stop will be routed so that they have approximately the same start times. |
location_groups | location group object list, optional | Location groups in which to place this stop. |
id | string | Id of the location group. |
ext_ref | string | External reference of the location group. |
At present, stops are limited to membership of a single location group. | ||
type | string, optional | Optional type of this stop. Does not affect behavior, at present. |
data | json, optional | Custom data to attach to this stop. |
autocomplete_rule | Specifies the conditions under which the stop should automatically be completed. | |
radius_metres | integer | The radius of the autocomplete circles, measured in metres. |
trigger_type | string | Specifies the kind of movement that should cause the autocomplete to happen. Must be one of enter , leave or enter_or_leave . |
can_complete_out_of_sequence | boolean | If true , the stop will autocomplete regardless of position in the driver's shift. Defaults to false , so only the next stop in a shift will autocomplete. |
target_article_ids | string list, optional | Ids of articles that are linked to this stop. |
The stop completion object
Example Object
{
"id": "12",
"stop_id": "f8168f4e-41dc-4971-aeb3-49f9c8fb69f7",
"stop_ext_ref": "2017-33232-1",
"ext_ref": "20170213111",
"time": "2017-02-13T12:00:00Z",
"is_by_token": true,
"shift_id": "1bbd4c14-d1a1-4f12-a6b8-e06c39d713cfu",
"attachments": [
{
"label": "Receipt Scan",
"media_type": "image/png"
},
{
"label": "Customer Signature",
"media_type": "application/pdf"
}
],
"attachment_ids": ["856", "862"],
"data": {
"reason": "Wasp infestation in the driveway."
},
"is_success": false,
"timezone": "Australia/Sydney",
"location": {
"latitude": -33.8925275,
"longitude": 151.2492009
},
"workflow_completion_id": "7723123829138",
}
The stop completion object is a record of when a stop was completed, whether or not it was completed successfully, and in which shift it was completed.
Attributes | ||
---|---|---|
id | integer | |
stop_id | string | Stop which this completion refers to. |
stop_id | string | External reference of the stop which this completion refers to. |
ext_ref | string | External reference of this stop completion. |
time | timestamp | Time that this stop was completed at. |
device_id | string | The id of the device used to complete this stop. |
shift_id | string | Shift in which this stop was completed in. |
attachments | File object list | Metadata for files attached to this job. Used to create new metadata for requests, and to return metadata for responses. |
attachment_ids | string list | Ids of existing files to attach to this job. Only used in requests. |
data | json | Custom data to attach to this stop. |
is_success | boolean | Indicates whether or not the work was performed successfully or not. |
timezone | string | The timezone in which the stop was completed, formatted according to the tz database. |
location | Location object, optional | The latitude and longitude at which the completion occurred, usually driver location. |
workflow_completion_id | string | The ID of the workflow completion that caused this stop completion, if any. |
Complete a stop
Example Request (using id)
# curl https://api.nowgo.io/v0/stops/{stop_id}/completions \
-u :{auth_token} \
-d {body}
Example Request (using external reference)
# curl https://api.nowgo.io/v0/stops/ext-ref/{ext_ref}/completions \
-u :{auth_token} \
-d {body}
Example Body
{
"time": "2017-02-13T12:00:00Z",
"stop_id": "f8168f4e-41dc-4971-aeb3-49f9c8fb69f7",
"shift_id": "1bbd4c14-d1a1-4f12-a6b8-e06c39d713cfu",
"ext_ref": "20170213111",
"is_success": false,
"attachments": [
{
"label": "Receipt Scan",
"media_type": "image/png"
}
],
"attachment_ids": ["856", "862"],
"data": {
"reason": "Wasp infestation in the driveway."
},
"timezone": "Australia/Sydney",
"location": {
"latitude": -33.8925275,
"longitude": 151.2492009
}
}
Example Response
{
"id": "12",
"stop_id": "f8168f4e-41dc-4971-aeb3-49f9c8fb69f7",
"ext_ref": "20170213111",
"time": "2017-02-13T12:00:00Z",
"shift_id": "1bbd4c14-d1a1-4f12-a6b8-e06c39d713cfu",
"is_success": false,
"attachments": [
{
"id": "862",
"name": "Order",
"media_type": "application/msword",
"has_content": false
},
{
"id": "901",
"label": "Receipt Scan",
"media_type": "image/png",
"has_content": true
}
],
"data": {
"reason": "Wasp infestation in the driveway."
},
"timezone": "Australia/Sydney",
"location": {
"latitude": -33.8925275,
"longitude": 151.2492009
}
}
Mark a stop as complete. This will create a record as a stop completion object. In doing so, the work that this stop represented will be considered as complete by the system.
It is possible to attach files to stop completions. Existing files are attached by adding their ids to the 'attachment_ids' field, whereas new files can be created by adding their metadata to the 'attachments' field. The response will include all file metadata including metadata for newly created files in the 'attachments' field. Note that a file's contents will need to be uploaded via a separate request. Learn how to create/upload files.
Stop Completions also have External references. Unlike other external references in NowGo, these are only unique per-stop. These are useful for de-duplicating stop completions when syncing them from another source. Premonition may also generate external references for stop completions, in the form of a Version 4 UUID.
Path Parameters | ||
---|---|---|
stop_id | string | Stop which this completion refers to. |
ext_ref | string | External reference of this stop this completion refers to. |
Body Parameters | ||
---|---|---|
stop_id | string | Stop which this completion refers to. |
ext_ref | string | External reference of this stop completion. |
time | timestamp, optional | Time that this stop was completed at. If this is omitted, the current system time will be used. |
shift_id | string, optional | Shift in which this stop was completed in. If this is omitted, the current assigned shift, if any, will be used. |
attachments | File object list | Metadata for new files to attach to this job. |
attachment_ids | string list | Ids for existing files to attach to this job. |
data | json, optional | Custom data to attach to this stop. |
is_success | boolean, optional | Indicates whether or not the work was performed successfully. Defaults to true if omitted. |
timezone | string, optional | The timezone in which the stop was completed, formatted according to the tz database. |
location | Location object, optional | The latitude and longitude at which the completion occurred, usually driver location. |
Response
Returns a stop completion object.
Retrieve completion details
Example Request (using id)
# curl https://api.nowgo.io/v0/stops/{stop_id}/completions \
-u :{auth_token}
Example Request (using external reference)
# curl https://api.nowgo.io/v0/stops/ext-ref/{ext_ref}/completions \
-u :{auth_token}
Retrieve all stop completion objects referring to this stop.
Path Parameters | ||
---|---|---|
stop_id | string | Stop which this completion refers to. |
ext_ref | string | External reference of the stop which this completion refers to. |
Validate stop locations
Example Request (with no arguments)
# curl https://api.nowgo.io/v0/stops/bad-geocodes \
-u :{auth_token}
Example Response (default pagination and parameters)
{
"results": [
{
"id": "605a9d83-b23f-4456-85c9-ae81277050d6",
"time_window_start": "2017-08-13T12:00:00Z",
"time_window_end": "2017-08-13T14:00:00Z",
"service_time": 240,
"location": {
"id": "123",
"address": "75 Bront Rd, Bondi Junction NSW 2022",
"latitude": 0,
"longitude": 0
}
}
],
"has_more": false
}
Example Request (restricting channel and time ranges)
# curl https://api.nowgo.io/v0/stops/bad-geocodes?channel_id=19&from=2017-08-14T00:00:00.000Z&until=2017-08-15T23:00:00.000Z \
-u :{auth_token}
Example Request (restricting channel using external reference)
# curl https://api.nowgo.io/v0/stops/bad-geocodes?channel_ext_ref=other_channel \
-u :{auth_token}
Example Request (pagination parameters)
# curl https://api.nowgo.io/v0/stops/bad-geocodes?limit=5&ending_before=605a9d83-b23f-4456-85c9-ae81277050d6 \
-u :{auth_token}
Returns stops which do not have a valid latitude
and longitude
.
As mentioned previously, if latitude
and longitude
are not provided,
the system will attempt to geocode the given address
and will use the best available result.
Sometimes this doesn't work, because the address
is invalid or is otherwise unable to be parsed by the system.
The result will be a stop with latitude
and longitude
values of 0
.
Stops such as these are returned by this endpoint.
This endpoint returns a paginated list. For more information about pagination and its parameters see here.
The search can be restricted to a specific channel by specifying the channel_id
or channel_ext_ref
query parameter. If neither of these are given, the response
will include stops from all channels.
The time range of the search can be restricted by specifying the from
and until
query parameters as timestamps conforming to ISO 8601, as demonstrated above.
Query Parameters | ||
---|---|---|
from | timestamp, optional | The start of the time range of this query. Stops which have a time_window_start at this time or after it will be included in this query. |
to | timestamp, optional | The end of the time range of this query. Stops which have a time_window_end before this time will be included in this query. |
channel_id | string, optional | Id of the channel that contains the stops. |
channel_ext_ref | string, optional | External reference of the channel that contains the stops. |
Response
Returns an array of stop objects where the latitude
and longitude
values were invalid.
The results are displayed in order of most recently updated first.
As a result, if a time range isn't specified using from
and to
, the most recently updated
stops with invalid coordinates will be displayed.
Delete a stop
Example Request (using id)
# curl https://api.nowgo.io/v0/stops/{stop_id} \
-X DELETE \
-u :{auth_token}
Example Request (using external reference)
# curl https://api.nowgo.io/v0/stops/ext-ref/{ext_ref} \
-X DELETE \
-u :{auth_token}
Example Request (in plan using id)
# curl https://api.nowgo.io/v0/plans/{plan_id}/stops/{stop_id} \
-X DELETE \
-u :{auth_token}
Example Request (in plan using external reference)
# curl https://api.nowgo.io/v0/plans/{plan_id}/stops/ext-ref/{ext_ref} \
-X DELETE \
-u :{auth_token}
Deletes a stop from its job. This operation is not reversible. Deleting a stop will not delete its completions, but will unassign the stop. Stops deleted this way will remain in unrefreshed plans.
This operation is available in plans.
Path Parameters | ||
---|---|---|
stop_id | string | The id of the stop being deleted. |
ext_ref | string | External reference of the stop being deleted. |
Consignments
The consignment object
Example object
{
"id": "729592901402625730",
"priority_id": "123456",
"priority_ext_ref": "high",
"is_return": null,
"ext_ref": null,
"articles": [
{
"consignment_id": "729592902600031",
"item_count": 1,
"identifiers": [
{
"is_primary_display_identifier": true,
"relation": null,
"identifier": "PPHP50WG01"
}
],
"id": "729592901485001",
"custom_data": {
"type": "CTN"
}
}
],
"receiver": {
"address_line_1": "55 Pyrmont Bridge Road",
"address_line_2": null,
"address_line_3": null,
"address_line_4": null,
"address_line_5": null
"postal_code": "2007",
"locality": "Pyrmont",
"state": "NSW",
"latitude": -33.87227166182225,
"longitude": 151.1946738493009,
"is_business": false,
"business_name": null,
"contact_phone": "0411111111",
"email": "test.user@example.com",
"contact_name": "Test User",
"custom_data": {},
},
"return_to": null,
"identifiers": [
{
"identifier": "PPHP580WI",
"relation": null,
"is_primary_display_identifier": true
}
],
"origin": null,
"sender": {
"id": "97500566829804483",
"name": "Stacey Smith",
"is_business": false,
"business_name": null,
"email": "staceysmith@example.com",
"address_line_1": "74 Forest Road",
"address_line_2": null,
"address_line_3": null,
"address_line_4": null,
"address_line_5": null,
"locality": "Springfield",
"state": "NSW",
"postal_code": "2020",
"contact_name": "Stacey Smith",
"contact_phone": "0412345678",
"latitude": "-33.9181216",
"longitude": "151.1470805",
"custom_data": {
"lorem": "ipsum",
"dolor": "sit amet",
"consectetur": "adipiscing elit"
}
},
"destination": null,
"custom_data": {
"dangerous_goods": false,
"authority_to_leave": false,
"delivery_instructions": "Signature Required"
},
}
You can read more about consignments in Further Concepts. Priorities are described in more detail in the priorities section.
To understand in clearer detail what a consignment is composed of, you may be interested in reading about:
The Party object, which describes how to specify sender, recipient and other addresses,
The Article object, which describes how to specify the contents of a consignment - e.g. the individually trackable physical objects to be delivered as part of this consignment,
The Consignment identifier object, which describes how to specify barcodes or identifiers for the consignment, and
The Article identifier object, which describes how to specify barcodes or identifiers for articles.
Attributes | ||
---|---|---|
id | string | |
identifiers | consignment identifier list, optional | List of consignment identifiers |
sender | party, optional | Party object specifying the person or entity who is to send the consignment. |
receiver | party, optional | Party object specifying the person or entity who is to receive the consignment. |
origin | party, optional | Party object specifying the location from which the consignment is sent. |
destination | party, optional | Party object specifying the location at which the consignment is received. |
is_return | boolean, optional | A Boolean specifying if this consignment is for a return. |
return_to | party, optional | Party object specifying the person or entity to which the consignment should be returned to. |
articles | article list, optional | List of articles on this consignment. |
priority_id | Id of the priority assigned to this job. | |
priority_ext_ref | External reference of the priority assigned to this job. | |
custom_data | json | Custom data attached to this consignment. |
The party object
Example object
{
"id": "97500566829804483",
"name": "Stacey Smith",
"is_business": false,
"business_name": null,
"email": "staceysmith@example.com",
"address_line_1": "74 Forest Road",
"address_line_2": null,
"address_line_3": null,
"address_line_4": null,
"address_line_5": null,
"locality": "Springfield",
"state": "NSW",
"postal_code": "2020",
"contact_name": "Stacey Smith",
"contact_phone": "0412345678",
"latitude": "-33.9181216",
"longitude": "151.1470805",
"custom_data": {
"lorem": "ipsum",
"dolor": "sit amet",
"consectetur": "adipiscing elit"
}
}
A party represents a person or entity that is related to a consignment. A party can contain information about the party's name, location, contact details, as well as additional custom data.
Attributes | ||
---|---|---|
name | string | Name of the entity associated with this party. |
is_business | boolean | A boolean specifying if this party is a business. |
business_name | string, optional | Name of the business associated with this party. |
string, optional | Email address associated with this party. | |
address_line_1 | string, optional | Address line one associated with this party. |
address_line_2 | string, optional | Address line two associated with this party. |
address_line_3 | string, optional | Address line three associated with this party. |
address_line_4 | string, optional | Address line four associated with this party. |
address_line_5 | string, optional | Address line five associated with this party. |
locality | string, optional | Suburb, township, or city in which this party is located. |
state | string, optional | State in which this party is located. |
postal_code | string, optional | Postal code of the location of this party. |
contact_name | string, optional | Contact name associated with this party. |
contact_phone | string, optional | Contact phone number associated with this party. |
latitude | double, optional | Latitude associated with this party. |
longitude | double, optional | Longitude associated with this party. |
custom_data | json, optional | Custom data attached to this party. |
The consignment identifier object
Example object
{
"identifier": "ABC123456789",
"relation": "label"
}
Attributes | ||
---|---|---|
identifier | string | An identifier on the consignment. |
relation | string | This identifier's relation to the consignment. |
Create a consignment
Example Request
# curl https://api.nowgo.io/v0/consignments \
-X PATCH \
-u :{auth_token} \
-d {body}
Example Body
{
"identifiers": [
{
"identifier": "PPHP580WI",
"relation": null,
"is_primary_display_identifier": true
}
],
"receiver": {
"id": "97500566829804483",
"name": "Stacey Smith",
"is_business": false,
"email": "staceysmith@example.com",
"address_line_1": "74 Forest Road",
"locality": "Springfield",
"state": "NSW",
"postal_code": "2020",
"contact_name": "Stacey Smith",
"contact_phone": "0412345678",
"latitude": "-33.9181216",
"longitude": "151.1470805",
"custom_data": {
"lorem": "ipsum",
"dolor": "sit amet",
"consectetur": "adipiscing elit"
}
},
"sender": {
"address_line_1": "55 Pyrmont Bridge Road",
"postal_code": "2007",
"locality": "Pyrmont",
"state": "NSW",
"latitude": -33.87227166182225,
"longitude": 151.1946738493009,
"is_business": false,
"contact_phone": "0411111111",
"email": "test.user@example.com",
"contact_name": "Test User",
"custom_data": {},
},
"origin": null,
"destination": null,
"is_return": false,
"return_to": {},
"articles": [
{
"identifiers": [
{
"is_primary_display_identifier": true,
"relation": null,
"identifier": "PPHP50WG01"
}
],
"item_count": 1,
"custom_data": {
"type": "CTN"
}
}
],
"priority_ext_ref": "high",
"custom_data": {
"dangerous_goods": false,
"authority_to_leave": false,
"delivery_instructions": "Signature Required"
}
}
Body Parameters | ||
---|---|---|
identifiers | consignment identifier list, optional | List of consignment identifiers |
sender | party, optional | Party object specifying the person or entity who is to send the consignment. |
receiver | party, optional | Party object specifying the person or entity who is to receive the consignment. |
origin | party, optional | Party object specifying the location from which the consignment is sent. |
destination | party, optional | Party object specifying the location at which the consignment is received. |
is_return | boolean, optional | A Boolean specifying if this consignment is for a return. |
return_to | party, optional | Party object specifying the person or entity to which the consignment should be returned to. |
articles | article list, optional | List of articles on this consignment. |
priority_id | string, optional | Id of the priority to set for the job. |
priority_ext_ref | string, optional | External reference of the priority to set for the consignment. |
Only one of priority_id and priority_ext_ref should be supplied. If both are supplied, the value of priority_id will be used. If neither is supplied, the consignment will use the organisation's default priority, if configured. |
||
custom_data | json | Custom data attached to this consignment. |
Response
Returns a consignment object if creation was successful. Returns an error if something goes wrong.
Retrieve a consignment
Example Request
# curl https://api.nowgo.io/v0/consignments/{consignment_id} \
-u :{auth_token}
Consignments can be retrieved using a consignment id.
Path parameters | ||
---|---|---|
consignment_id | string | The id of the consignment to be retrieved. |
Update a consignment
Example Request
# curl https://api.nowgo.io/v0/consignments/{consignment_id} \
-X PATCH \
-u :{auth_token} \
-d {body}
Example Body
{
"identifiers": [{}],
"sender": {},
"receiver": {},
"origin": {},
"destination": {},
"is_return": false,
"return_to": {},
"articles": [{}],
"priority_ext_ref": "high",
"custom_data": {
"lorem": "ipsum",
"dolor": "sit amet",
"consectetur": "adipiscing elit"
}
}
Applies an update to the given consignment. Any parameters set to null
in the request will be cleared if valid. Any parameters not passed in the request will remain unchanged. You can read more about the semantics of PATCH
in updating resources.
Path parameters | ||
---|---|---|
consignment_id | string | The id of the consignment to be updated. |
Body Parameters | ||
---|---|---|
identifiers | consignment identifier list, optional | List of consignment identifiers |
sender | party, optional | Party object specifying the person or entity who is to send the consignment. |
receiver | party, optional | Party object specifying the person or entity who is to receive the consignment. |
origin | party, optional | Party object specifying the location from which the consignment is sent. |
destination | party, optional | Party object specifying the location at which the consignment is received. |
is_return | boolean, optional | A Boolean specifying if this consignment is for a return. |
return_to | party, optional | Party object specifying the person or entity to which the consignment should be returned to. |
articles | article list, optional | List of articles on this consignment. |
priority_id | string, optional | Id of the priority to set for the job. |
priority_ext_ref | string, optional | External reference of the priority to set for the consignment. |
Only one of priority_id and priority_ext_ref should be supplied. If both are supplied, the value of priority_id will be used. If neither is supplied, the consignment will use the organisation's default priority, if configured. |
||
custom_data | json | Custom data attached to this consignment. |
Search for consignments
Example Request
# curl https://api.nowgo.io/v0/consignments/search?identifier=BARCODE1000&page_size=100 \
-u :{auth_token}
Returns a paginated list of consignment objects consignments matching the identifier
query parameter.
This query will return consignments which either have a matching consignment identifier, or have an associated article with a matching article identifier.
Query parameters | ||
---|---|---|
identifier | string | The identifier (e.g. label or barcode number) you are searching for. |
page_size | int, optional | How many consignment objects to return at a time. |
page_token | string, optional | Page token for the next page of results. |
Articles
The article object
Example object
{
"id": "47500564578487767",
"consignment_id": "47829599378998346",
"identifiers": [
{
"identifier": "XGS4983189",
"relation": "label_number"
},
{
"identifier": "XGS2393721",
"relation": "additional_reference"
}
],
"item_count": "1",
"custom_data": {
"lorem": "ipsum",
"dolor": "sit amet",
"consectetur": "adipiscing elit"
},
"notes": "lorem ipsum"
}
You can read more about articles in Further Concepts.
Attributes | ||
---|---|---|
id | string | |
consignment_id | string | The id of the consignment this article belongs to. |
identifiers | article identifier list | List of article identifiers. |
item_count | string | Number of physical items that are part of this article. |
custom_data | JSON | Custom data attached to this article. |
notes | string | Notes attached to this article. |
The article identifier object
Example object
{
"identifier": "XGS4983189",
"relation": "label_number"
}
Attributes | ||
---|---|---|
identifier | string | An identifier on the consignment. |
relation | string | The identifier's relation to the article. |
Create an article
Example Request
# curl https://api.nowgo.io/v0/consignments/-/articles \
-X PATCH \
-u :{auth_token} \
-d {body}
Example Body
{
"identifiers": [
{
"identifier": "XGS4983189",
"relation": "label_number"
},
{
"identifier": "XGS2393721",
"relation": "additional_reference"
}
],
"item_count": "1",
"custom_data": {
"lorem": "ipsum",
"dolor": "sit amet",
"consectetur": "adipiscing elit"
},
"notes": "Lorem ipsum, dolor sit amet"
}
Body Parameters | ||
---|---|---|
consignment_id | string | The id of the consignment this article belongs to. |
identifiers | article identifier list | List of article identifiers. |
item_count | string | Number of physical items that are part of this article. |
custom_data | JSON, optional | Custom data attached to this article. |
notes | string, optional | Notes attached to this article. |
Retrieve an article
Example Request
# curl https://api.nowgo.io/v0/consignments/-/articles/{article_id} \
-u :{auth_token}
Articles can be retrieved using a consignment id and article id.
Path Parameters | ||
---|---|---|
article_id | string | The id of the article to be retrieved. |
Update an article
Example Request
# curl https://api.nowgo.io/v0/consignments/-/articles/{article_id} \
-X PATCH \
-u :{auth_token} \
-d {body}
Example Body
{
"identifiers": [
{
"identifier": "XGS4983189",
"relation": "label_number"
},
{
"identifier": "XGS2393721",
"relation": "additional_reference"
}
],
"item_count": "1",
"custom_data": {
"lorem": "ipsum",
"dolor": "sit amet",
"consectetur": "adipiscing elit"
},
"notes": "Lorem ipsum, dolor sit amet"
}
Applies an update to the given article. Any parameters set to null
in the request will be cleared if valid. Any parameters not passed in the request will remain unchanged. You can read more about the semantics of PATCH
in updating resources.
Path Parameters | ||
---|---|---|
article_id | string | The id of the article to be updated. |
Body Parameters | ||
---|---|---|
consignment_id | string | The id of the consignment this article belongs to. |
identifiers | article identifier list | List of article identifiers. |
item_count | string | Number of physical items that are part of this article. |
custom_data | JSON, optional | Custom data attached to this article. |
notes | string, optional | Notes attached to this article. |
Actions
Actions can be (and are typically) configured via the NowGo Dashboard, however there are API methods that allow API users to create, read and update actions. See actions for more details.
The action object
Example object
{
"id": "6631",
"display_name": "Pickup",
"ext_ref": "pickup",
"legacy_stop_type": "pickup",
"legacy_workflow_type": null,
"color": "#00e397"
"archived_at": null,
"outcomes": [{
"id": "125",
"code": "failed-already-picked-up",
"display_name": "Unsuccessful pickup - already picked up",
"archived_at": null
}, {
"id": "437",
"code": "succeeded-pickup",
"display_name": "Successful pickup",
"archived_at": null
}]
}
You can read more about actions in Key Concepts.
Attributes | ||
---|---|---|
id | string | The identifier of the action. |
display_name | string | The display name that will be shown when viewing the action. |
ext_ref | string | The organisation's external reference for the action. |
legacy_stop_type | string, optional | The legacy stop type that this action should be associated with (e.g pickup, dropoff). |
legacy_workflow_type | string, optional | The legacy workflow type that this action should be associated with (e.g pickup, deliver). |
color | string, optional | A hexadecimal string representing the color of the action when rendered in the NowGo app. |
archived_at | string, optional | An ISO compliant date string representing when the action was archived. |
outcomes | List of outcomes | A list of outcomes associated with the action. An action must have at least 1 outcome. |
The action outcome object
Example object
{
"id": "437",
"code": "succeeded-pickup",
"display_name": "Successful pickup",
"archived_at": null
}
The action outcome field is used to specify what the possible results or outcomes exist for a workflow completion using actions. The code
field will be returned as the outcome
` field of the workflow completion. See the workflow completion API for more information.
Attributes | ||
---|---|---|
id | string | The identifier of the outcome. |
code | string | A string representing information about the outcome. |
display_name | string | A human-friendly string that is displayed in the NowGo app and dashboard. |
archived_at | string, optional | An ISO compliant date string representing when the outcome was archived. |
Create an action
Example Request
curl https://api.nowgo.io/v0/actions \
-X POST \
-u :{auth_token} \
-d {body}
Example Body
{
"display_name": "Pickup",
"ext_ref": "pickup",
"color": "#00e397"
"outcomes": [{
"code": "failed-already-picked-up",
"display_name": "Unsuccessful pickup - already picked up",
}, {
"code": "succeeded-pickup",
"display_name": "Successful pickup",
}]
}
Body Parameters | ||
---|---|---|
display_name | string | The display name that will be shown when viewing the action. |
ext_ref | string | The organisation's external reference for the action. |
color | string, optional | A hexadecimal string representing the color of the action when rendered in the NowGo app. |
outcomes | List of outcomes | A list of outcomes associated with the action. An action must have at least 1 outcome. |
Retrieve an action
Example Request
curl https://api.nowgo.io/v0/actions/{action_id} \
-u :{auth_token}
curl https://api.nowgo.io/v0/actions/ext-ref/{action_ext_ref} \
-u :{auth_token}
Actions can be retrieved via their id
.
Path Parameters | ||
---|---|---|
action_id | string | The id of the action to be retrieved. |
Actions can also be retrieved via their ext_ref
.
Path Parameters (ext_ref ) |
||
---|---|---|
action_ext_ref | string | The ext_ref of the action to be retrieved. |
List actions
Example Request
curl https://api.nowgo.io/v0/actions \
-u :{auth_token}
Example Response
{
"data": [
{
"id": "6631",
"display_name": "Pickup",
"ext_ref": "pickup",
"legacy_stop_type": "pickup",
"legacy_workflow_type": null,
"color": "#00e397"
"archived_at": null,
"outcomes": [{
"id": "125",
"code": "failed-already-picked-up",
"display_name": "Unsuccessful pickup - already picked up",
"archived_at": null
}, {
"id": "437",
"code": "succeeded-pickup",
"display_name": "Successful pickup",
"archived_at": null
}]
}
],
"next_page_token": null
}
All existing actions in your org can be queried for. Note that the response is returned in a paginated manner.
Query parameters | ||
---|---|---|
archived | boolean, optional | Whether to return archived actions or not. By default this is false . |
all | boolean, optional | Whether to return both archived and non-archived actions. By default this is false . |
page_size | int, optional | How many action objects to return at a time. |
page_token | string, optional | Page token for the next page of results. |
Update an action
Example Request
curl https://api.nowgo.io/v0/actions/{action_id} \
-X PATCH \
-u :{auth_token} \
-d {body}
curl https://api.nowgo.io/v0/actions/ext-ref/{action_ext_ref} \
-X PATCH \
-u :{auth_token} \
-d {body}
Example Body
{
"display_name": "Pickup (new color)",
"ext_ref": "pickup_new_color",
"color": "#ef9a21"
}
Applies an update to the given action. Any fields set to null
in the request will be cleared if valid. Any fields not passed in the request will remain unchanged. You can read more about the semantics of PATCH
in updating resources.
Path Parameters | ||
---|---|---|
action_id | string | The id of the action to be updated. |
Actions can also be updated via their ext_ref
.
Path Parameters (ext_ref ) |
||
---|---|---|
action_ext_ref | string | The ext_ref of the action to be updated. |
Body Parameters | ||
---|---|---|
display_name | string | The display name that will be shown when viewing the action. |
ext_ref | string | The organisation's external reference for the action. |
legacy_stop_type | string, optional | The legacy stop type that this action should be associated with (e.g pickup, dropoff). |
legacy_workflow_type | string, optional | The legacy workflow type that this action should be associated with (e.g pickup, deliver). |
color | string, optional | A hexadecimal string representing the color of the action when rendered in the NowGo app. |
outcomes | List of outcomes | A list of outcomes associated with the action. An action must have at least 1 outcome. Note that if you want to add a new outcome, you have to pass all of the existing outcomes as well the new outcome you want to add. If existing outcomes are omitted from the list, they will be archived. |
Archiving an action
Example Request
curl https://api.nowgo.io/v0/actions/{action_id} \
-X DELETE \
-u :{auth_token}
curl https://api.nowgo.io/v0/actions/ext-ref/{action_ext_ref} \
-X DELETE \
-u :{auth_token}
Path Parameters | ||
---|---|---|
action_id | string | The id of the action to be archived. |
Actions can also be archived via their ext_ref
.
Path Parameters (ext_ref ) |
||
---|---|---|
action_ext_ref | string | The ext_ref of the action to be archived. |
Drivers
The driver object
Example object
{
"id": "44482",
"ext_ref": "driver772",
"name": "Andrew Jones",
"email": "d772@courier.com",
"phone": "+61400000000",
"is_password_set": true,
"travel_duration_multiplier": 1.2,
"calculated_travel_duration_multiplier": 1.1,
"use_calculated_travel_duration_multiplier": false,
"require_sso": false,
"default_channel_id": "1234",
"default_channel_ext_ref": "channel1",
"data": {
"lorem": "ipsum",
"dolor": "sit amet"
}
}
Attributes | ||
---|---|---|
id | string | |
ext_ref | string | External reference for the driver. |
name | string | Display name for the driver. |
string | Unique email for the driver. | |
phone | string | Unique phone number for the driver. |
is_password_set | boolean | If the driver currently has a password set, this field contains true . |
use_calculated_travel_duration_multiplier | boolean | If true , the automatically-calculated travel duration multiplier is used for this driver. If false , the manually-set travel_duration_multiplier is used. If null , the default setting for the organisation is used, which is false by default. |
travel_duration_multiplier | double | Multiplier applied to driver travel times. For example, a travel_duration_multiplier of 1.2 means a driver is 20% slower than base calculated times. |
calculated_travel_duration_multiplier | double | Same as travel_duration_multiplier but automatically calculated by NowGo at regular intervals if the automated driver efficiency feature is set-up. |
require_sso | boolean | If true , force users to log in with Single Sign On (SSO). Has no effect if SSO is not configured. |
default_channel_id | string | ID of the driver's default channel. |
default_channel_ext_ref | string | External reference of the driver's default channel. |
data | json | Custom data attached to this driver. |
For more information about Single Sign On, contact our team.
Create a driver
Example request
$ curl https://api.nowgo.io/v0/drivers \
-u :{auth_token} \
-d {body}
Example body
{
"ext_ref": "driver772",
"name": "Andrew Jones",
"email": "d772@example.com",
"phone": "+61400000000",
"password": "verysecretpw",
"use_calculated_travel_duration_multiplier": false,
"travel_duration_multiplier": 1.2,
"default_channel_id": "1234",
"default_channel_ext_ref": "channel1",
"data": {
"lorem": "ipsum",
"dolor": "sit amet"
}
}
Body Parameters | ||
---|---|---|
ext_ref | string, optional | External reference for the driver. |
name | string, optional | Display name for the driver. This will be shown in the dashboard. |
string, optional | Email that the driver can use to log in to the Driver App. This is unique to your organization. If omitted, drivers will not be able to log in to the Driver App. | |
phone | string, optional | Phone for the driver. This is used for password resets. |
password | string, optional | Password that will be required to log in to the Driver App. At present, no requirements are enforced on password contents or complexity. If omitted, drivers will not be able to log in to the Driver App. This value can never be retrieved. |
use_calculated_travel_duration_multiplier | boolean, optional | If true , the automatically-calculated travel duration multiplier is used for this driver. If false , the manually-set travel_duration_multiplier is used. If null , the default setting for the organisation is used, which is false by default. |
travel_duration_multiplier | double, optional | Multiplier applied to driver travel times. For example, a travel_duration_multiplier of 1.2 means a driver is 20% slower than base calculated times. |
require_sso | boolean, optional | If true , force users to log in with Single Sign On (SSO). Has no effect if SSO is not configured. |
default_channel_id | string, optional | ID of the driver's default channel. |
default_channel_ext_ref | string, optional | External reference of the driver's default channel. |
data | json, optional | Custom data attached to this driver. |
Response
Returns a driver object if creation was successful. Returns an error if something goes wrong.
Retrieve a driver
Example Request (using id)
# curl https://api.nowgo.io/v0/drivers/{id} \
-u :{auth_token}
Example Request (using external reference)
# curl https://api.nowgo.io/v0/drivers/ext-ref/{ext_ref} \
-u :{auth_token}
Drivers can be retrieved using their id or external reference.
Path Parameters | ||
---|---|---|
id | string | The id of the driver to be retrieved. |
ext_ref | string | The external reference of the driver to be retrieved. |
Response
Returns a driver object if the given identifier is valid, and returns an error otherwise.
Retrieve all drivers
Example Request
# curl https://api.nowgo.io/v0/drivers \
-u :{auth_token}
Query Parameters | ||
---|---|---|
page_size | int, optional | How many driver objects to return at a time. |
page_token | string, optional | Page token for the next page of results. |
Example Response
Returns a paginated list of driver objects.
{
"data": [{}],
"next_page_token": "db05252b"
}
Alternative pagination styles
The /v0/drivers
endpoint also supports page-based pagination, which was exposed
in the API but never documented. If you're not already using that style of pagination on this endpoint, please use
token-based pagination as described above.
Update a driver
Example request (using id)
$ curl https://api.nowgo.io/v0/drivers/{id} \
-X PATCH \
-u :{auth_token} \
-d {body}
Example request (using external reference)
$ curl https://api.nowgo.io/v0/drivers/ext-ref/{ext_ref} \
-X PATCH \
-u :{auth_token} \
-d {body}
Example body
{
"name": "Andrew Jones",
"email": null,
"phone": "+61400000000",
"use_calculated_travel_duration_multiplier": false,
"travel_duration_multiplier": 1.3,
"default_channel_id": "1234",
"default_channel_ext_ref": "channel1",
"data": {
"lorem": "ipsum",
"dolor": "sit amet",
"consectetur": "adipiscing elit"
}
}
Applies an update to the given driver. Any parameters set to null in the request will be cleared if valid. Any parameters not passed in the request will remain unchanged. You can read more about the semantics of PATCH in updating resources.
Path Parameters | ||
---|---|---|
id | string | The id of the driver being updated. |
ext_ref | string | External reference of the driver. |
Body Parameters | ||
---|---|---|
ext_ref | string | External reference of the driver. |
name | string, optional | Display name for the driver. This will be shown in the dashboard. |
string, optional | Email that the driver can use to log in to the Driver App. This is unique to your organization. If not set, drivers will not be able to log in to the Driver App. | |
phone | string, optional | Phone for the driver. This is used for password resets. |
use_calculated_travel_duration_multiplier | boolean, optional | If true , the automatically-calculated travel duration multiplier is used for this driver. If false , the manually-set travel_duration_multiplier is used. If null , the default setting for the organisation is used, which is false by default. |
travel_duration_multiplier | double, optional | Multiplier applied to driver travel times. For example, a travel_duration_multiplier of 1.2 means a driver is 20% slower than base calculated times. |
require_sso | boolean, optional | If true , force users to log in with Single Sign On (SSO). Has no effect if SSO is not configured. |
default_channel_id | string, optional | ID of the driver's default channel. |
default_channel_ext_ref | string, optional | External reference of the driver's default channel. |
data | json, optional | Custom data attached to this driver. |
Response
Returns a driver object if the update was successful. Returns an error if something goes wrong.
Archive a driver
Example request (using id)
$ curl https://api.nowgo.io/v0/drivers/{id} \
-X DELETE \
-u :{auth_token}
Example request (using external reference)
$ curl https://api.nowgo.io/v0/drivers/ext-ref/{ext_ref} \
-X DELETE \
-u :{auth_token}
Archives a driver.
When a driver is archived via the API, the driver’s external reference is cleared and can be used again elsewhere. An archived driver can be restored via the restore
endpoint.
Path Parameters | ||
---|---|---|
id | string | The id of the driver being archived. |
ext_ref | string | External reference of the driver being archived. |
Response
Returns a driver object if the archive was successful. Returns an error if something goes wrong.
Restore a driver
Example request
$ curl https://api.nowgo.io/v0/drivers/{id}/restore \
-X POST \
-u :{auth_token} \
-d {body}
Restores a driver.
When a driver is restored via the API, the driver’s new external reference can be set using the ext_ref
parameter (this must not conflict with any existing, unarchived drivers).
Path Parameters | ||
---|---|---|
id | string | The id of the driver being restored. |
Body Parameters | ||
---|---|---|
ext_ref | string | External reference of the driver. |
reset_password | string, optional | Force reset the password of the driver account, defaults to false |
enable_account | string, optional | Determines if the driver account is active, defaults to true . |
Response
Returns a driver object if the restoration was successful. Returns an error if something goes wrong, such as when a conflicting external reference is used.
Update a driver's location
Example Request (using id)
$ curl https://api.nowgo.io/v0/drivers/{id}/tracking-points \
-u :{auth_token} \
-d {body}
Example Request (using external reference)
$ curl https://api.nowgo.io/v0/drivers/ext-ref/{ext_ref}/tracking-points \
-u :{auth_token} \
-d {body}
Example body
{
"latitude": -33.8605187,
"longitude": 151.2039825,
"time": "2017-01-01T05:24:41Z"
}
Adds a tracking point for a driver. If the tracking point is more recent than those from other sources, stop etas and other time-dependent calculations are also updated accordingly.
Path Parameters | ||
---|---|---|
id | string | The id of the driver. |
ext_ref | string | External reference of the driver. |
Body Parameters | ||
---|---|---|
latitude | double | Latitude of the location. |
longitude | double | Longitude of the location. |
time | timestamp | Time at which the driver was at the location. NowGo will not perform any corrections on this time to account for discrepancies between its current time and the client's current time. |
The created point's provider
field will contain the value api
.
Response
Returns 200 Ok
if the location update was successful. Returns an error if something goes wrong.
Get a driver's travel history
Example Request (using id)
$ curl https://api.nowgo.io/v0/drivers/{id}/track?date=2017-01-01 \
-u :{auth_token}
Example Request (using external reference)
$ curl https://api.nowgo.io/v0/drivers/ext-ref/{ext_ref}/track?date=2017-01-01 \
-u :{auth_token}
Returns information about a driver's travel. This information is gathered from in-app location tracking, driver locations added via the API, and from stop completion information. If no time range is specified, this endpoint returns the most recent known location of the driver.
Path Parameters | ||
---|---|---|
id | string | Id of the driver to retrieve information for. |
ext_ref | string | External reference of the driver to retrieve information for. |
Query Parameters | ||
---|---|---|
date | date, optional | Date of information to be retrieved. This will be interpreted as a 24-hour period in the timezone 'Australia/Sydney'. |
Example Response
{
"driver_id": "4321",
"points": [
{
"provider": "gps",
"time": "2017-01-01T05:24:41Z",
"latitude": -33.8605187,
"longitude": 151.2039825,
"accuracy": 11.3
},
{
"provider": "completion",
"time": "2017-01-01T05:25:00Z",
"latitude": -33.8605187,
"longitude": 151.2039825,
"stop_id": "58cacd4e-4f9f-47bc-9a2f-74e5ffc67ad5"
}
]
}
Response
An object containing driver id, and a list of points. If the list of points is empty, no location information is available for the driver within the requested period.
Attributes | |
---|---|
provider | Source of the location information. This may be gps for tracking information, or completion if the location is that of a completed stop. Other vendor-specific values may also be returned from phones. |
time | Time at which the point occurred. This may differ from the original time reported by the driver's phone, if the system shows the driver's clock is not correct. |
accuracy | Accuracy of the given coordinates in metres, if available. |
stop_id | If the location was inferred from a stop completion, this indicates the specific stop that was completed. |
Update the locations of many drivers
Example Request
$ curl https://api.nowgo.io/v0/tracking-points \
-u :{auth_token} \
-d {body}
Example body
[
{
"driver_id": "4321",
"latitude": -33.8605187,
"longitude": 151.2039825,
"time": "2017-01-01T05:24:41Z"
},
{
"driver_ext_ref": "driver_13",
"latitude": -33.8688,
"longitude": 151.2093,
"time": "2017-01-01T05:24:41Z"
}
]
Adds many tracking points from a list of tracking point objects. Each object consists of an id or external reference of a driver along with coordinates and a time stamp.
Body Parameters | ||
---|---|---|
driver_id | string | The id of the driver. |
driver_ext_ref | string | External reference of the driver. |
latitude | double | Latitude of the location. |
longitude | double | Longitude of the location. |
time | timestamp | Time at which the driver was at the location. NowGo will not perform any corrections on this time to account for discrepancies between its current time and the client's current time. |
Channels
The channel object
Example object
{
"id": "44482",
"ext_ref": "sydney-west",
"name": "Sydney West",
"ext_version": 3371645,
"bounding_box_enabled": true,
"bounding_box_north": -33.8207615,
"bounding_box_south": -34.0819139,
"bounding_box_east": 151.0422459,
"bounding_box_west": 150.6851903,
"timezone": "Australia/Sydney",
"delegated_channel_ids:": ["44483", "ext-ref-channel-1"]
}
Attributes | ||
---|---|---|
id | string | |
ext_ref | string | External reference for the channel. |
name | string | Display name for the channel. |
ext_version | string | External version for the channel, if any. |
bounding_box_enabled | boolean | true if the channel has a bounding box applied. |
bounding_box_north | double | Northern extent of the channel. |
bounding_box_south | double | Southern extent of the channel. |
bounding_box_east | double | Eastern extent of the channel. |
bounding_box_west | double | Western extent of the channel. |
archived | boolean | true if the channel is currently archived. |
timezone | string | Timezone code of the channel. |
delegated_channel_ids | string list | Delegated channel ids associated with this channel. This can be an Id or an ext-ref. |
See additional documentation on bounding box |
Bounding Box
Channels in NowGo can optionally have a bounding box. The bounding box is used to filter geocode results for stops in the channel. If a stop geocodes to a point outside the channel bounding box, the point is presumed to be incorrect and not used.
Create a channel
Example request
$ curl https://api.nowgo.io/v0/channels \
-u :{auth_token} \
-d {body}
Example body
{
"ext_ref": "sydney-west",
"name": "Sydney West",
"bounding_box_enabled": true,
"bounding_box_north": -33.8207615,
"bounding_box_south": -34.0819139,
"bounding_box_east": 151.0422459,
"bounding_box_west": 150.6851903,
"timezone": "Australia/Sydney",
"delegated_channel_ids:": ["ext-ref-channel-2"]
}
Body Parameters | ||
---|---|---|
ext_ref | string, optional | External reference for the channel. |
name | string, optional | Display name for the channel. This will be shown in the dashboard. |
bounding_box_enabled | boolean, optional | true if the channel has a bounding box applied. |
bounding_box_north | double, optional | Northern extent of the channel |
bounding_box_south | double, optional | Southern extent of the channel |
bounding_box_east | double, optional | Eastern extent of the channel |
bounding_box_west | double, optional | Western extent of the channel |
timezone | string | Timezone code of the channel. |
delegated_channel_ids | string list | Delegated channel ids associated with this channel. This can be an Id or an ext-ref. |
See additional documentation on bounding box |
Response
Returns a channel object if creation was successful. Returns an error if something goes wrong.
Update a channel
Example request (using id)
$ curl https://api.nowgo.io/v0/channels/{id} \
-X PATCH \
-u :{auth_token} \
-d {body}
Example request (using external reference)
$ curl https://api.nowgo.io/v0/channels/ext-ref/{ext_ref} \
-X PATCH \
-u :{auth_token} \
-d {body}
Example body
{
"name": "Sydney Northwest",
"ext_version": 100,
"bounding_box_enabled": true,
"bounding_box_north": -33.8207615,
"bounding_box_south": -34.0819139,
"bounding_box_east": 151.0422459,
"bounding_box_west": 150.6851903,
"timezone": "Australia/Sydney",
"delegated_channel_ids:": ["ext-ref-channel-2"]
}
Applies an update to the given channel. Any parameters set to null in the request will be cleared if valid. Any parameters not passed in the request will remain unchanged. You can read more about the semantics of PATCH in updating resources.
Path Parameters | ||
---|---|---|
id | string | The id of the channel being modified. |
ext_ref | string | External reference for the channel. |
Body Parameters | ||
---|---|---|
name | string, optional | Display name for the channel. This will be shown in the dashboard. |
ext_version | integer, optional | External version for the channel, if any. |
bounding_box_enabled | boolean, optional | true if the channel has a bounding box applied. |
bounding_box_north | double, optional | Northern extent of the channel. |
bounding_box_south | double, optional | Southern extent of the channel. |
bounding_box_east | double, optional | Eastern extent of the channel. |
bounding_box_west | double, optional | Western extent of the channel. |
archived | boolean, optional | true if the channel should be archived. |
timezone | string | Timezone code of the channel. |
delegated_channel_ids | string list | Delegated channel ids associated with this channel. This can be an Id or an ext-ref. |
See additional documentation on bounding box |
Response
Returns a channel object if the update was successful. Returns an error if something goes wrong.
Retrieve a channel
Example Request (using id)
# curl https://api.nowgo.io/v0/channels/{id} \
-u :{auth_token}
Example Request (using external reference)
# curl https://api.nowgo.io/v0/channels/ext-ref/{ext_ref} \
-u :{auth_token}
Channel objects can be retrieved using their ids or external references.
Path Parameters | ||
---|---|---|
id | string | The id of the channel being retrieved. |
ext_ref | string | External reference of the channel being retrieved. |
Response
Returns a channel object if the request is valid.
Retrieve all channels
Example Request
# curl https://api.nowgo.io/v0/channels \
-u :{auth_token}
Query Parameters | ||
---|---|---|
page_size | int, optional | How many channel objects to return at a time. |
page_token | string, optional | Page token for the next page of results. |
archived | string, optional | Filters results to only archived or non-archived channels. Pass true to retrieve only archived channels, or false to retrieve only non-archived channels. Note that the behaviour of this parameter is different to other endpoints, as a request without the parameter included will return all channels. |
Example Response
Returns a paginated list of channel objects.
{
"data": [{}],
"next_page_token": "db05252b"
}
Plans
The plan object
You can read more about plans in Further Concepts.
Example object
{
"id": "44234",
"shift_ids": ["4412", "4413", "4416"],
"shifts": [{}],
"job_ids": ["44516531", "5615251"],
"jobs": [{}]
}
The plan object contains a snapshot of the state of the world at a particular point in time. You can change the contents of a plan without worrying about concurrent modification, and then resolve any conflicts at a later point. Plans are always created within the context of a channel, and cannot cross channel boundaries.
Updates to plans use a similar set of operations and endpoints as updates to other entities. See the Interacting with plans section for more information.
Attributes | ||
---|---|---|
id | string | |
shift_ids | string list | Ids of shifts captured by the plan. |
shifts | Shift object list | Shifts captured by the plan. |
job_ids | string list | Ids of jobs captured by the plan. |
jobs | Job object list | Jobs captured by the plan. |
Create a plan
Example request (using id)
$ curl https://api.nowgo.io/v0/channels/{channel_id}/plans \
-u :{auth_token} \
-d {body}
Example request (using external reference)
$ curl https://api.nowgo.io/v0/channels/ext-ref/{channel_ext_ref}/plans \
-u :{auth_token} \
-d {body}
Example body based on specific shifts and jobs
{
"shift_ids": ["4412", "4413", "4416"],
"job_ids": ["44516531", "5615251"]
}
Example body based on a time window
{
"time_window_start": "2017-01-01T08:00:00Z",
"time_window_end": "2017-01-01T17:00:00Z"
}
Path Parameters | ||
---|---|---|
channel_id | string | Id of the channel on which to base the plan. |
channel_ext_ref | string | External reference of the channel on which to base the plan. |
Body Parameters | ||
---|---|---|
To create a plan based on a window of time: | ||
time_window_start | timestamp, optional | Time from which the plan should start capturing contents. |
time_window_end | timestamp, optional | Time to which the plan should capture contents. |
To create a plan based on specific contents: | ||
shift_ids | string list, optional | Ids of shifts to capture in the plan. |
job_ids | string list, optional | Ids of jobs to capture in the plan. |
If a time window and specific ids are both present, only entities matching the ids provided will be included in the plan. This can be useful for attempting to assign a specific job, for example. If a plan is created with an empty list of ids, no entities of that type will be included. Note that some additional entities may be brought into the plan if they are attached to entities that are explicitly included (for example, including a shift will include its assigned stops and jobs).
Response
Returns a plan object if creation was successful. Returns an error if something goes wrong.
Retrieve a plan
Example Request (using id)
# curl https://api.nowgo.io/v0/channels/{channel_id}/plans/{id} \
-u :{auth_token}
Example Request (using external reference)
# curl https://api.nowgo.io/v0/channels/ext-ref/{channel_ext_ref}/plans/{id} \
-u :{auth_token}
Path Parameters | ||
---|---|---|
channel_id | string | The id of the channel on which the plan is based. |
channel_ext_ref | string | The external reference of the channel on which the plan is based. |
id | string | The id of the plan to be retrieved. |
Merge a plan
Example Request (using id)
# curl https://api.nowgo.io/v0/channels/{channel_id}/plans/{id}/merge \
-X POST
-u :{auth_token}
Example Request (using external reference)
# curl https://api.nowgo.io/v0/channels/ext-ref/{channel_ext_ref}/plans/{id}/merge \
-X POST
-u :{auth_token}
Path Parameters | ||
---|---|---|
channel_id | string | The id of the channel on which the plan is based. |
channel_ext_ref | string | The external reference of the channel on which the plan is based. |
id | string | The id of the plan to be merged. |
Body Parameters | ||
---|---|---|
allow_conflicts | boolean, optional | If true, changes made in the plan will be applied to the world, even if the world has since changed. This may cause unexpected results, including undoing changes made in the world. Stops that have been completed, however, will remain completed. |
update_before_merge | boolean, optional | If true, the plan will be updated with changes in the world since the plan was created. This can be used to mitigate the risk of merge conflicts in high volume networks. |
Update a plan
Example Request (using id)
# curl https://api.nowgo.io/v0/channels/{channel_id}/plans/{id}/fix \
-X POST
-u :{auth_token}
Example Request (using external reference)
# curl https://api.nowgo.io/v0/channels/ext-ref/{ext_ref}/plans/{id}/fix \
-X POST
-u :{auth_token}
Interacting with plans
Plans use similar endpoints and requests as other operations. Not all endpoints are supported in plans. When an endpoint is supported, the documentation will contain an example of performing an operation on a plan.
Common operations
Jobs
Stops
- Add stops to a job in a plan
- Retrieve a stop in a plan
- Update a stop in a plan
- Delete a stop in a plan
Solves
The solve object
You can read more about solves in Further Concepts.
Example object
{
"id": "5152",
"solve_profile_ext_ref": "full-solve",
"status": "in-progress",
"all_shifts_locked": false,
"shift_ids": ["4414"],
"locked_shift_ids": ["4414, 4415"],
"all_unassigned_jobs_locked": true,
"job_ids": [],
"locked_job_ids": []
}
The solve object contains information about a currently running or completed solve operation. The solve object also contains information about the shifts and jobs currently locked within the plan due to the solve.
Attributes | ||
---|---|---|
id | string | |
solve_profile_ext_ref | string | External reference of the profile used to complete the solve. |
status | string | Current status of the plan. Expected values are: in-progress , complete , cancelled , failed . |
all_shifts_locked | boolean | If true, the solve has locked all shifts in the relevant plan and so they should not be updated until the solve is complete. |
shift_ids | string list | If all_shifts_locked is false , contains ids of shifts being solved. If all_shifts_locked is true , the contents is undefined. |
locked_shift_ids | string list | If all_shifts_locked is false , contains ids of shifts locked by the solve. These shifts should not be updated until the solve is complete. If all_shifts_locked is true , the contents is undefined. |
all_unassigned_jobs_locked | boolean | If true, the solve has locked all unassigned jobs in the relevant plan and so they should not be updated until the solve is complete. |
job_ids | string list | If all_jobs_locked is false , contains ids of jobs being solved. If all_jobs_locked is true , the contents is undefined. |
locked_job_ids | string list | If all_jobs_locked is false , contains ids of jobs locked by the solve. These jobs should not be updated until the solve is complete. If all_jobs_locked is true , the contents is undefined. |
Create a solve
Example request (using channel id)
$ curl https://api.nowgo.io/v0/channels/{channel_id}/plans/{plan_id}/solves \
-u :{auth_token} \
-d {body}
Example request (using channel external reference)
$ curl https://api.nowgo.io/v0/channels/ext-ref/{channel_ext_ref}/plans/{plan_id}/solves \
-u :{auth_token} \
-d {body}
Example body
{
"solve_profile_ext_ref": "full-solve",
"shift_ids": ["4414"],
"job_ids": ["1141", "1146"],
"exclude_unassigned_jobs": true
}
When a solve is created, NowGo begins working in the background to complete it. When a solve is completed, any effects are applied in the plan automatically. You can retrieve a plan at any time to check its current status.
Path Parameters | ||
---|---|---|
channel_id | string | Id of the channel on which the plan to be solved is based. |
channel_ext_ref | string | External reference of the channel on which the plan to be solved is based. |
plan_id | string | Id of the plan in which to solve. |
Body Parameters | ||
---|---|---|
solve_profile_ext_ref | string | The type of solve to perform. See the table below for more information on this parameter. |
shift_ids | string list, optional | Specific shifts to include in the solve. If omitted or empty, all shifts in the relevant plan will be included. Any jobs with stops currently assigned to those shifts will also be included. |
job_ids | string list, optional | Specific jobs to include in the solve. If omitted or empty, all jobs in the relevant plan will be included unless the exclude_unassigned_jobs parameter is true . |
exclude_unassigned_jobs | boolean, optional | If true, no unassigned jobs will be included in the solve. |
Default solve profiles
solve_profile_ext_ref | |
---|---|
full |
Performs a solve using all given shifts, allowing jobs to move between shifts and become unassigned (unless specifically prevented with the frozen or sticky properties). |
allocate |
Performs a solve aimed at allocating more work to drivers. Does not drop any already assigned stops. |
allocate_together |
Performs a solve aimed at allocating more work to drivers. Does not drop any already assigned stops. Allocates all unassigned stops to a single driver, or not at all. |
Response
Returns a solve object if creation was successful. Returns an error if something goes wrong.
Retrieve a solve
Retrieves the status of a solve. Possible values for status
include:
in-progress
- the solve is still pending.complete
- the solve has completed, and the plan has been updated accordinglycancelled
- the solve has been cancelled, through user request or otherwise.failed
- an error has occurred during the solve
Example Request (using channel id)
# curl https://api.nowgo.io/v0/channels/{channel_id}/plans/{plan_id}/solves/{id} \
-u :{auth_token}
Example Request (using channel external reference)
# curl https://api.nowgo.io/v0/channels/ext-ref/{channel_ext_ref}/{plan_id}/solves/{id} \
-u :{auth_token}
Path Parameters | ||
---|---|---|
channel_id | string | The id of the channel on which the plan is based. |
channel_ext_ref | string | The external reference of the channel on which the plan is based. |
plan_id | string | Id of the plan on which the solve is based. |
id | string | The id of the solve to be retrieved. |
List all solves in progress
Example Request (using channel id)
# curl https://api.nowgo.io/v0/channels/{channel_id}/plans/{plan_id}/solves \
-u :{auth_token}
Example Request (using channel external reference)
# curl https://api.nowgo.io/v0/channels/ext-ref/{channel_ext_ref}/plans/{plan_id}/solves \
-u :{auth_token}
Path Parameters | ||
---|---|---|
channel_id | string | The id of the channel on which the plan is based. |
channel_ext_ref | string | The external reference of the channel on which the plan is based. |
plan_id | string | Id of the plan on which the solves are based. |
Response
Returns the list of currently in-progress
solve objects for the specified plan and channel.
Capacities
The capacity object
You can read more about capacities in Further Concepts.
Example Response
{
"id": "11314",
"ext_ref": "weight-kgs",
"name": "Weight (kgs)",
"service_time_seconds_per_unit": 0.2,
"is_weight": true,
"session_weight_unit": "kilograms",
"app_weight_unit": "kilograms",
"default_limit_setting": "default_zero"
}
Attributes | ||
---|---|---|
id | string | |
ext_ref | string | External reference for the capacity. |
name | string | Name for the capacity. |
service_time_seconds_per_unit | string | Seconds of service time to add to stops per unit of capacity. |
is_weight | string | True if the capacity should be displayed as a weight. |
session_weight_unit | string | Unit to use for displaying the weight in the dashboard ("tonnes", "kilograms", "grams", "milligrams", "stone", "pounds", "ounces"). |
app_weight_unit | string | Unit to use for displaying the weight in the app ("tonnes", "kilograms", "grams", "milligrams", "stone", "pounds", "ounces"). |
default_limit_setting | string | Behavior when a vehicle or vehicle type doesn't have a corresponding capacity configured. "default_zero" will treat the vehicle as having no available capacity, while "default_max_value" will treat the vehicle as having no limit for the capacity. |
Create a capacity
Example Request
# curl https://api.nowgo.io/v0/capacities \
-u :{auth_token} \
-d {body}
Example Body
{
"ext_ref": "weight-kgs",
"name": "Weight (kgs)",
"service_time_seconds_per_unit": 0.2,
"is_weight": true,
"session_weight_unit": "kilograms",
"app_weight_unit": "kilograms",
"default_limit_setting": "default_zero"
}
Body Parameters | ||
---|---|---|
ext_ref | string, optional | External reference for the capacity. |
name | string | Name for the capacity. |
service_time_seconds_per_unit | string, optional | Seconds of service time to add to stops per unit of capacity. |
is_weight | string, optional | True if the capacity should be displayed as a weight. |
session_weight_unit | string, optional | Unit to use for displaying the weight in the dashboard ("tonnes", "kilograms", "grams", "milligrams", "stone", "pounds", "ounces"). |
app_weight_unit | string, optional | Unit to use for displaying the weight in the app ("tonnes", "kilograms", "grams", "milligrams", "stone", "pounds", "ounces"). |
default_limit_setting | string, optional | Behavior when a vehicle or vehicle type doesn't have a corresponding capacity configured. "default_zero" will treat the vehicle as having no available capacity, while "default_max_value" will treat the vehicle as having no limit for the capacity. |
Response
Returns a capacity object if creation was successful. Returns an error if something goes wrong.
Retrieve capacities
Example Request
# curl https://api.nowgo.io/v0/capacities \
-u :{auth_token}
Example Response
[
{
"id": "9226",
"ext_ref": "weight-kgs",
"name": "Weight (kgs)",
"is_weight": true,
"session_weight_unit": "kilograms",
"app_weight_unit": "kilograms"
},
{
"id": "4154"
"ext_ref": "volume-m3",
"name": "Volume (m3)"
}
]
Response
A list of capacity objects.
Attributes
The attribute object
You can read more about attributes in Further Concepts.
Example Response
{
"id": "321",
"name": "Refrigerated",
"ext_ref": "is-refrigerated",
"is_boolean": true
}
Attributes | ||
---|---|---|
id | string | |
ext_ref | string | External reference for the attribute. |
name | string | The attribute's human-readable name |
is_boolean | boolean | If true, the attribute is boolean, else it is numeric. |
Create an attribute
Example Request
# curl https://api.nowgo.io/v0/attributes \
-u :{auth_token} \
-d {body}
Example Body
{
"name": "Refrigerated",
"ext_ref": "is-refrigerated",
"is_boolean": true
}
Body Parameters | ||
---|---|---|
ext_ref | string, optional | External reference for the attribute. |
name | string | The attribute's human-readable name |
is_boolean | boolean | If true, the attribute is boolean, else it is numeric. |
Response
Returns an attribute object if creation was successful. Returns an error if something goes wrong.
Retrieve attributes
Example Request
# curl https://api.nowgo.io/v0/attributes \
-u :{auth_token}
Example Response
[
{
"id": "3957",
"name": "Refrigerated",
"ext_ref": "is-refrigerated",
"is_boolean": true
},
{
"id": "293",
"name": "Vehicle height",
"ext_ref": "vehicle-height",
"is_boolean": false
}
]
Response
A list of attribute objects.
Vehicle Types
The vehicle type object
You can read more about vehicle types in Vehicle Types. Vehicle attributes (attribute values) are described in more detail in Further Concepts.
Example Response
{
"id": "5256",
"ext_ref": "large-van",
"capacity_limits": [
{
"capacity_id": "552132",
"capacity_ext_ref": "weight-kgs",
"limit": 1540
},
{
"capacity_id": "5525",
"capacity_ext_ref": "volume-m3",
"limit": 7
}
],
"attribute_values": [
{
"attribute_id": "56",
"attribute_ext_ref": "is-refrigerated",
"value": true
},
{
"attribute_id": "83",
"attribute_ext_ref": "capacity-kg",
"value": 2000
}
],
"travel_duration_multiplier": 1.2
}
Attributes | ||
---|---|---|
id | string | |
ext_ref | string | External reference for the vehicle type. |
name | string | Name for the vehicle type. |
capacity_limits | object list | Capacity limits of the vehicle type. |
capacity_id | string | Id of the capacity. |
capacity_ext_ref | string | External Reference of the capacity. |
limit | integer | Limit of the capacity for this vehicle type. |
attribute_values | object list | Attribute values of the vehicle type. |
attribute_id | string | Id of the attribute. |
attribute_ext_ref | string | External Reference of the attribute. |
value | integer or boolean | Value of the attribute for this vehicle type. |
travel_duration_multiplier | double | Multiplier applied to vehicle type travel times. For example, a travel_duration_multiplier of 1.2 means a vehicle type is 20% slower than base calculated times. |
Create a vehicle type
Example Request
# curl https://api.nowgo.io/v0/vehicle-types \
-u :{auth_token} \
-d {body}
Example Body
{
"ext_ref": "large-van",
"name": "Large van",
"capacity_limits": [
{
"capacity_ext_ref": "weight-kgs",
"limit": 1540
},
{
"capacity_id": "5525",
"limit": 7
}
],
"attribute_values": [
{
"attribute_id": "938",
"value": 5
},
{
"attribute_ext_ref": "is-refrigerated",
"value": false
}
],
"travel_duration_multiplier": 1.2
}
Body Parameters | ||
---|---|---|
ext_ref | string, optional | External reference for the capacity. |
name | string | Name for the vehicle type. |
capacity_limits | object list, optional | Capacity limits of the vehicle type. |
capacity_id | string | Id of the capacity. |
capacity_ext_ref | string | External Reference of the capacity. |
One of capacity_id and capacity_ext_ref must be provided. |
||
limit | integer | Limit of the capacity for this vehicle type. |
attribute_values | object list, optional | Attribute values of the vehicle type. |
attribute_id | string | Id of the attribute. |
attribute_ext_ref | string | External Reference of the attribute. |
value | integer or boolean | Value of the attribute for this vehicle type. |
travel_duration_multiplier | double | Multiplier applied to vehicle type travel times. For example, a travel_duration_multiplier of 1.2 means a vehicle type is 20% slower than base calculated times. |
Response
Returns a vehicle type object if creation was successful. Returns an error if something goes wrong.
Retrieve vehicle types
Example Request
# curl https://api.nowgo.io/v0/vehicle-types \
-u :{auth_token}
Example Response
[
{
"id": "5256",
"ext_ref": "large-van",
"name": "Large van",
"capacity_limits": [
{
"capacity_id": "552132",
"capacity_ext_ref": "weight-kgs",
"limit": 1540
},
{
"capacity_id": "5525",
"capacity_ext_ref": "volume-m3",
"limit": 7
}
],
"attribute_values": [
{
"attribute_id": "56",
"attribute_ext_ref": "is-refrigerated",
"value": true
},
{
"attribute_id": "83",
"attribute_ext_ref": "capacity-kg",
"value": 2000
}
]
},
{
"id": "515",
"ext_ref": "motorbike",
"capacity_limits": [
{
"capacity_id": "62",
"capacity_ext_ref": "max-jobs",
"limit": 12
}
],
"attribute_values": [
{
"attribute_id": "4",
"attribute_ext_ref": "has-tailgate",
"value": false
}
]
}
]
Response
A list of vehicle type objects.
Retrieve a vehicle type
Example Request (using id)
# curl https://api.nowgo.io/v0/vehicle-types/{id} \
-u :{auth_token}
Example Request (using external reference)
# curl https://api.nowgo.io/v0/vehicle-types/ext-ref/{ext_ref} \
-u :{auth_token}
Vehicle type objects can be retrieved by id or external reference.
Path Parameters | ||
---|---|---|
id | string | The id of the vehicle type being retrieved. |
ext_ref | string | External reference of the vehicle type being retrieved. |
Response
Returns a vehicle type object if the request is valid.
Update a vehicle type
Example Request (using id)
# curl -X PATCH https://api.nowgo.io/v0/vehicle-types/{id} \
-u :{auth_token} \
-d {body}
Example Request (using external reference)
# curl -X PATCH https://api.nowgo.io/v0/vehicle-types/ext-ref/{ext_ref} \
-u :{auth_token}
Example Body
{
"travel_duration_multiplier": 1.2,
"name": "Large van",
"capacity_limits": [
{
"capacity_ext_ref": "weight-kgs",
"capacity_id": "10",
"limit": 1500
},
{
"capacity_ext_ref": "litres",
"capacity_id": "5"
}
],
"attribute_values": [
{
"attribute_id": "11",
"attribute_ext_ref": "is-refrigerated",
"value": false
},
{
"attribute_id": "16",
"attribute_ext_ref": "vehicle-height-metres",
"value": 3
}
]
}
This endpoint allows us to update vehicle types.
If either the capacity_limits
and attribute_values
object lists are included in the request, they will overwrite their respective existing values. As such, you should include all values, including the parameters you wish to change, as well as those that should remain the same. Otherwise, if the entire list is omitted, no changes to those fields will be applied, following PATCH
semantics.
Changing vehicle type parameters such as capacity_limits
or attribute_values
may make existing data in shifts and solves invalid. It could mean that already existing shifts and solves using the old parameters will be in place and won't match up with new requirements. This could be addressed by reattempting a solve using the new vehicle type parameters.
Path Parameters | ||
---|---|---|
id | string | The id of the vehicle type being updated. |
ext_ref | string | External reference of the vehicle type being updated. |
Body Parameters | ||
---|---|---|
name | string | Name for the vehicle type. |
travel_duration_multiplier | double | Multiplier applied to vehicle type travel times. For example, a travel_duration_multiplier of 1.2 means a vehicle type is 20% slower than base calculated times. |
capacity_limits | object list, optional | Capacity limits of the vehicle type. |
capacity_id | string | Id of the capacity. |
capacity_ext_ref | string | External Reference of the capacity. |
One of capacity_id and capacity_ext_ref must be provided. |
||
limit | integer | Limit of the capacity for this vehicle type. |
attribute_values | object list, optional | Attribute values of the vehicle type. |
attribute_id | string | Id of the attribute. |
attribute_ext_ref | string | External reference of the attribute. |
value | integer or boolean | Value of the attribute for this vehicle type. |
Response
Returns a vehicle type object if the update was successful. Returns an error if something goes wrong.
Vehicles
The vehicle object
Further Concepts contains more detail about vehicles as well as the related concepts of vehicle types, attributes and attribute values and capacities and capacity limits.
Example Response
{
"name": "PA312X (Truck)",
"ext_ref": "large-truck25",
"vehicle_type_ext_ref": "large-refrigerated-truck",
"id": "932",
"vehicle_type_id": "3744",
"capacity_limits": [
{
"state": "overridden",
"limit": 2000,
"capacity_ext_ref": "weight-kgs",
"capacity_id": "10"
},
{
"state": "deleted",
"capacity_ext_ref": "litres",
"capacity_id": "4"
}
],
"attribute_values": [
{
"attribute_id": "11",
"attribute_ext_ref": "is-refrigerated",
"state": "inherited",
"value": true
},
{
"attribute_id": "16",
"attribute_ext_ref": "vehicle-height-metres",
"state": "new",
"value": 14
}
]
}
Attributes | ||
---|---|---|
id | string | |
name | string, optional | The name of the vehicle. |
ext_ref | string | External reference for the vehicle. |
vehicle_type_id | string, optional | Id of the vehicle's vehicle type |
vehicle_type_ext_ref | string, optional | External reference for the vehicle's vehicle type. |
capacity_limits | object list | Capacity limits of the vehicle. |
state | string | Inheritance relationship to vehicle type's capacity limit |
capacity_id | string | Id of the capacity. |
capacity_ext_ref | string | External Reference of the capacity. |
limit | integer, optional | Limit of the capacity for this vehicle. Omitted when the state is 'deleted'. |
attribute_values | object list | Attribute values of the vehicle. |
attribute_id | string | Id of the attribute. |
attribute_ext_ref | string | External reference of the attribute. |
state | string | Inheritance relationship to vehicle type's attribute value |
value | integer or float, optional | Value of the attribute for this vehicle. Omitted when the state is 'deleted'. |
Create a vehicle
Example Request
# curl https://api.nowgo.io/v0/vehicles \
-u :{auth_token} \
-d {body}
Example Body
{
"name": "Refrigerated Van III",
"ext_ref": "refrigerated-van-3",
"vehicle_type_ext_ref": "refrigerated-vans",
"vehicle_type_id": "112",
"capacity_limits": [
{
"capacity_ext_ref": "weight-kgs",
"limit": 2000
}
],
"attribute_values": [
{
"attribute_id": "67",
"value": true
},
{
"attribute_ext_ref": "is-refrigerated",
"value": true
},
{
"attribute_id": "16",
"attribute_ext_ref": "vehicle-height-metres",
"value": 2
}
]
}
Body Parameters | ||
---|---|---|
name | string, optional | A name for the vehicle. |
ext_ref | string, optional | External reference for the vehicle. |
vehicle_type_id | string, optional | The id of the vehicle's vehicle type. |
vehicle_type_ext_ref | string, optional | The external reference of the vehicle's vehicle type |
One of vehicle_type_id and vehicle_type_ext_ref must be provided. |
||
capacity_limits | object list, optional | Capacity limits of the vehicle (includes limits inherited from the vehicle type). |
capacity_id | string | Id of the capacity. |
capacity_ext_ref | string | External Reference of the capacity. |
One of capacity_id and capacity_ext_ref must be provided. |
||
limit | integer | Limit of the capacity for this vehicle. |
attribute_values | object list, optional | Attribute values of the vehicle type (includes attribute values inherited from the vehicle type). |
attribute_id | string | Id of the attribute. |
attribute_ext_ref | string | External reference of the attribute. |
value | integer or boolean | Value of the attribute for this vehicle. |
Response
Returns a vehicle object if creation was successful. Returns an error if something goes wrong.
Retrieve vehicles
Example Request
# curl https://api.nowgo.io/v0/vehicles \
-u :{auth_token}
Example Response
{
"page": 1,
"totalPages": 1,
"totalResults": 3,
"results": [
{
"id": "1",
"name": "Toyota Van",
"ext_ref": "large-van13",
"vehicle_type_ext_ref": "large-capacity-van",
"vehicle_type_id": "1",
"capacity_limits": [],
"attribute_values": [
{
"attribute_id": "4",
"attribute_ext_ref": "has-tailgate",
"state": "inherited",
"value": true
}
]
},
{
"id": "3",
"name": null,
"ext_ref": "large-van7",
"vehicle_type_ext_ref": "large-capacity-van",
"vehicle_type_id": "1",
"capacity_limits": [],
"attribute_values": [
{
"attribute_id": "4",
"attribute_ext_ref": "has-tailgate",
"state": "deleted"
},
{
"attribute_id": "12",
"attribute_ext_ref": "is-refrigerated",
"state": "new",
"value": false
}
]
},
{
"id": "5",
"name": null,
"ext_ref": "moped-14",
"vehicle_type_ext_ref": "moped",
"vehicle_type_id": "5",
"capacity_limits": [
{
"state": "overridden",
"capacity_id": "62",
"capacity_ext_ref": "weight-kgs",
"limit": 45
}
],
"attribute_values": []
}
]
}
Response
A paginated list of vehicle objects.
Retrieve a vehicle
Example Request (using id)
# curl https://api.nowgo.io/v0/vehicles/{id} \
-u :{auth_token}
Example Request (using external reference)
# curl https://api.nowgo.io/v0/vehicles/ext-ref/{ext_ref} \
-u :{auth_token}
Vehicle objects can be retrieved using their ids or external references.
Path Parameters | ||
---|---|---|
id | string | The id of the vehicle being retrieved. |
ext_ref | string | External reference of the vehicle being retrieved. |
Response
Returns a vehicle object if the request is valid.
Update a vehicle
Example Request (using id)
# curl -X PATCH https://api.nowgo.io/v0/vehicles/{id} \
-u :{auth_token} \
-d {body}
Example Request (using ext ref)
# curl -X PATCH https://api.nowgo.io/v0/vehicles/ext-ref/{ext_ref} \
-u :{auth_token} \
-d {body}
Example Body
{
"capacity_limits": [
{
"capacity_ext_ref": "weight-kgs",
"capacity_id": "10",
"limit": 1500
},
{
"capacity_ext_ref": "litres",
"capacity_id": "5"
}
],
"attribute_values": [
{
"attribute_id": "11",
"attribute_ext_ref": "is-refrigerated",
"value": false
},
{
"attribute_id": "16",
"attribute_ext_ref": "vehicle-height-metres",
"value": 3
}
]
}
This endpoint allows us to update capacity limits and attribute values of vehicles.
If either the capacity_limits
and attribute_values
object lists are included in the request, they will overwrite their respective existing values. As such, you should include all values, including the parameters you wish to change, as well as those that should remain the same. Otherwise, if the entire list is omitted, no changes to those fields will be applied, following PATCH
semantics.
Changing vehicle parameters such as capacity_limits
or attribute_values
may make existing data in shifts and solves invalid. It could mean that already existing shifts and solves using the old parameters will be in place and won't match up with new requirements. This could be addressed by reattempting a solve using the new vehicle parameters.
Path Parameters | ||
---|---|---|
id | string | The id of the vehicle being updated. |
ext_ref | string | External reference of the vehicle being updated. |
Body Parameters | ||
---|---|---|
name | string, optional | The name of the vehicle. |
capacity_limits | object list, optional | Capacity limits of the vehicle (includes limits inherited from the vehicle type). |
capacity_id | string | Id of the capacity. |
capacity_ext_ref | string | External Reference of the capacity. |
One of capacity_id and capacity_ext_ref must be provided. |
||
limit | integer | Limit of the capacity for this vehicle. |
attribute_values | object list, optional | Attribute values of the vehicle type (includes attribute values inherited from the vehicle type). |
attribute_id | string | Id of the attribute. |
attribute_ext_ref | string | External reference of the attribute. |
value | integer or boolean | Value of the attribute for this vehicle. |
Response
Returns a vehicle object if the update was successful. Returns an error if something goes wrong.
Delete a vehicle
Example request (using id)
# curl https://api.nowgo.io/v0/vehicles/{vehicle_id} \
-u :{auth_token} \
-X DELETE
Example request (using external reference)
# curl https://api.nowgo.io/v0/vehicles/ext-ref/{vehicle_ext_ref} \
-u :{auth_token} \
-X DELETE
Deletes a vehicle.
When a vehicle is deleted via the API, the vehicle's external reference is cleared and can be used again elsewhere.
Path Parameters | ||
---|---|---|
vehicle_id | string | The id of the vehicle being deleted. |
vehicle_ext_ref | string | The external reference of the vehicle being deleted. |
Priorities
The priority object
Example object
{
"id": "2",
"ext_ref": "medium",
"is_default": true,
"priority_multiplier": 2.0,
"display_importance": 3,
"display_name": "Medium",
"archived": false
}
The priority object is used to set the priority level of jobs and consignments. The priority_multiplier
attribute is used by the optimisation engine to influence sequencing and allocation.
Attributes | ||
---|---|---|
id | string | |
ext_ref | string | External reference for the priority. Priority ext_ref s are mutable, unlike their equivalents in other objects. |
priority_multiplier | double | Optional, specifies the relative priority level assigned to the priority object. Defaults to 1.0 . |
is_default | boolean | Optional, specifies if this priority is the default. Default priorities are used when no priority is provided on a job or consignment. Defaults to false . |
display_importance | integer | Optional, used in the UI of the Dashboard and Driver App to determine the display of prioritiy icons. Values 1, 2 and 3 will show an icon. Defaults to 0 . |
display_name | string | String used in the UI of the Dashboard and Driver App. |
archived | boolean | Specifies if the priority is archived. |
Create a priority
Example Request
# curl https://api.nowgo.io/v0/priorities \
-u :{auth_token} \
-d {body}
Example Request (with default override)
# curl https://api.nowgo.io/v0/priorities?can_change_default=true \
-u :{auth_token} \
-d {body}
Example Body
{
"ext_ref": "medium",
"display_name": "Medium",
"priority_multiplier": 2,
"display_importance": 2,
"is_default": true,
"archived": false
}
Body Parameters | ||
---|---|---|
ext_ref | string | External reference for the priority. Priority ext_ref s are mutable, unlike their equivalents in other objects. |
priority_multiplier | double, optional | Optional, specifies the relative priority level assigned to the priority object. Defaults to 1.0 . |
is_default | boolean, optional | Optional, specifies if this priority is the default. Default priorities are used when no priority is provided on a job or consignment. Defaults to false . |
display_importance | integer, optional | Optional, used in the UI of the Dashboard and Driver App to determine the display of prioritiy icons. Values 1, 2 and 3 will show an icon. Defaults to 0 . |
display_name | string | String used in the UI of the Dashboard and Driver App. |
archived | boolean | Specifies if the priority is archived. |
The endpoint accepts the following query parameters:
Query Parameters | ||
---|---|---|
can_change_default | boolean, optional | Allows the default priority to be set when a default priority already exists in the organisation. Using this parameter when creating a priority with is_default equal to true will unset the existing default, if one is set. Defaults to false. |
Response
Returns a priority object if creation was successful. Returns an error if something goes wrong.
Retrieve a priority
Example Request (using id)
# curl https://api.nowgo.io/v0/priorities/{id} \
-u :{auth_token}
Example Request (using ext_ref)
# curl https://api.nowgo.io/v0/priorities/ext_ref/{ext_ref} \
-u :{auth_token}
Priority objects can be retrieved using their ids or external references.
Path Parameters | ||
---|---|---|
id | string | The id of the priority being retrieved. |
ext_ref | string | External reference for the priority being retrieved. |
Response
Returns a priority object if the request was valid. Returns an error if something goes wrong.
Update a priority
Priorities can be modified using PATCH. They can be referred to using either an id or an external reference. See above for request body examples.
Example Request (using id)
# curl https://api.nowgo.io/v0/priorities/{id} \
-u :{auth_token} \
-d {body}
Example Request (using ext_ref)
# curl https://api.nowgo.io/v0/priorities/ext_ref/{ext_ref} \
-u :{auth_token} \
-d {body}
Example Request (with default override)
# curl https://api.nowgo.io/v0/priorities/{id}?can_change_default=true \
-u :{auth_token} \
-d {body}
Example Body
{
"ext_ref": "high",
"display_name": "High",
"priority_multiplier": 3,
"display_importance": 3,
"is_default": true,
"archived": false
}
Path Parameters | ||
---|---|---|
id | string | The id of the priority being updated. |
ext_ref | string | External reference for the priority being updated. |
Body Parameters | ||
---|---|---|
ext_ref | string | External reference for the priority. Priority ext_ref s are mutable, unlike their equivalents in other objects. |
priority_multiplier | double, optional | Optional, specifies the relative priority level assigned to the priority object. Defaults to 1.0 . |
is_default | boolean, optional | Optional, specifies if this priority is the default. Default priorities are used when no priority is provided on a job or consignment. Defaults to false . |
display_importance | integer, optional | Optional, used in the UI of the Dashboard and Driver App to determine the display of prioritiy icons. Values 1, 2 and 3 will show an icon. Defaults to 0 . |
display_name | string | String used in the UI of the Dashboard and Driver App. |
archived | boolean | Specifies if the priority is archived. |
The endpoint accepts the following query parameters:
Query Parameters | ||
---|---|---|
can_change_default | boolean, optional | Allows the default priority to be set when a default priority already exists in the organisation. Using this parameter when updating a priority with is_default equal to true will unset the existing default, if one is set. Defaults to false. |
Response
Returns a priority object if update was successful. Returns an error if something goes wrong.
Retrieve all priorities
Example Request (with no arguments)
# curl https://api.nowgo.io/v0/priorities \
-u :{auth_token}
Example Response (default pagination and parameters)
{
"page": 1,
"totalPages": 1,
"totalResults": 3,
"results": [
{
"is_default": true,
"priority_multiplier": 2.0,
"display_importance": 2,
"archived": false,
"ext_ref": "medium",
"display_name": "Medium",
"id": "1"
},
{
"is_default": false,
"priority_multiplier": 4.0,
"display_importance": 3,
"archived": false,
"ext_ref": "high",
"display_name": "High",
"id": "2"
},
{
"is_default": false,
"priority_multiplier": 1.0,
"display_importance": 0,
"archived": false,
"ext_ref": "low",
"display_name": "Low",
"id": "3"
}
]
}
Example Request (show_archived)
# curl https://api.nowgo.io/v0/priorities?show_archived=true \
-u :{auth_token}
Example Request (show_all)
# curl https://api.nowgo.io/v0/priorities?show_all=true \
-u :{auth_token}
Example Request (search)
# curl https://api.nowgo.io/v0/priorities?q=high \
-u :{auth_token}
This endpoint returns a paginated list. For more information about pagination and its parameters see here.
Query Parameters | ||
---|---|---|
show_archived | boolean, optional | Only priorities that are archived will be included in this query. Defaults to false. |
show_all | boolean, optional | All priorities (archived and not archived ) will be included in this query. Defaults to false. |
q | string, optional | When specified, priorities containing the query string in either the display_name or ext_ref will be included in this query. Defaults to no query string filter. |
Response
Returns a paginated list of priorities matching either the specified parameters, or the defaults parameters if none are specified.
Locations
The location object
Example Object
{
"id": "124",
"display_name": "Depot",
"type": "depot",
"address": "123 Foundry Rd",
"locality": "Seven Hills",
"state": "NSW",
"postal_code": "2147",
"country": "AU",
"latitude": -33.769299,
"longitude": 150.956357,
"geocode": true,
"data": {
"Notes": "etc"
},
"ext_ref": "depot",
"display_label": "123F",
"geocoded_address": "123 Foundry Rd, Seven Hills, NSW, 2147"
}
Attributes | ||
---|---|---|
id | string | |
display_name | string | A name or description of this location. This is displayed in the dashboard. |
ext_ref | string | External reference for the location. Location ext_ref s are mutable, unlike their equivalents in other objects. |
address | string | Human-readable address of the location. This will be displayed to dispatchers and drivers. |
locality | string | Suburb, township, or city of this location. This will be displayed to dispatchers and drivers. |
state | string | State of the location. |
postal_code | string | Postal code of the location. |
country | string | Country of the location. |
latitude | double | Latitude of the location. If no latitude and longitude coordinates are provided, NowGo will attempt to geocode this location. |
longitude | double | Longitude of the location. If no latitude and longitude coordinates are provided, NowGo will attempt to geocode this location. |
geocode | boolean | An explicit request to the system to attempt to geocode the location, overwriting any existing latitude and longitude coordinates. If set to true, NowGo will attempt to geocode this location, if set to false, no attempt will be made. If no value is passed, the system will only geocode if no valid coordinates were passed in. |
type | string | Optional type of this location. Displayed in the dashboard. |
data | json | Custom data to attach to this location. |
display_label | string | Optional, four-character maximum label attached to this location which is used as a visual identifier in the dashboard. |
geocoded_address | string | An address returned by the system after a geocoding attempt, representing the best possible interpretation of the address field. |
Create a location
Example Request
# curl https://api.nowgo.io/v0/locations \
-u :{auth_token} \
-d {body}
Example Body
{
"display_name": "Depot",
"type": "depot",
"address": "123 Foundry Rd",
"locality": "Seven Hills",
"state": "NSW",
"postal_code": "2147",
"country": "AU",
"latitude": -33.769299,
"longitude": 150.956357,
"geocode": true,
"data": {
"Notes": "etc"
},
"ext_ref": "depot",
"display_label": "123F"
}
Body Parameters | ||
---|---|---|
display_name | string, optional | A name or description of this location. This is displayed in the dashboard. |
ext_ref | string, optional | External reference for the location. Location ext_ref s are mutable, unlike their equivalents in other objects. |
address | string | Human-readable address of the location. This will be displayed to dispatchers and drivers. |
locality | string | Suburb, township, or city of this location. This will be displayed to dispatchers and drivers. |
state | string | State of the location. |
postal_code | string | Postal code of the location. |
country | string | Country of the location. |
latitude | double, optional | Latitude of the location. If no latitude and longitude coordinates are provided, NowGo will attempt to geocode this location. |
longitude | double, optional | Longitude of the location. If no latitude and longitude coordinates are provided, NowGo will attempt to geocode this location. |
geocode | boolean, optional | An explicit request to the system to attempt to geocode the location, overwriting any existing latitude and longitude coordinates. If set to true, NowGo will attempt to geocode this location, if set to false, no attempt will be made. If no value is passed, the system will only geocode if no valid coordinates were passed in. |
type | string, optional | Optional type of this location. Displayed in the dashboard. |
data | json, optional | Custom data to attach to this location. |
display_label | string, optional | Optional, four-character maximum label attached to this location which is used as a visual identifier in the dashboard. |
Response
Returns a location object if the request was valid. If the location was geocoded, it will return the calculated latitude and longitude, as well as the amended address from which these coordinates were based off.
Update a location
Example Request (using id)
# curl https://api.nowgo.io/v0/locations/{id} \
-X PATCH \
-u :{auth_token} \
-d {body}
Example Request (using ext_ref)
# curl https://api.nowgo.io/v0/locations/ext-ref/{ext_ref} \
-X PATCH \
-u :{auth_token} \
-d {body}
Locations can be modified using PATCH. They can be referred to using either an id or an external reference. See above for request body examples.
Modifying an existing location will not modify any stops created from or referring to the original location, unless the update_open_stops
flag is set to true
. In this case, NowGo will automatically update any stops and plan stops that reference the location and are not closed. This is useful for globally correcting bad geocodes, for example.
Path Parameters | ||
---|---|---|
id | string | |
ext_ref | string, optional | External reference for the location. |
Body Parameters | ||
---|---|---|
ext_ref | string, optional | External reference for the location. Location ext_ref s are mutable, unlike their equivalents in other objects. |
display_name | string, optional | A name or description of this location. This is displayed in the dashboard. |
address | string | Human-readable address of the location. This will be displayed to dispatchers and drivers. |
locality | string | Suburb, township, or city of this location. This will be displayed to dispatchers and drivers. |
state | string | State of the location. |
postal_code | string | Postal code of the location. |
country | string | Country of the location. |
latitude | double, optional | Latitude of the location. If no latitude and longitude coordinates are provided, NowGo will attempt to geocode this location. |
longitude | double, optional | Longitude of the location. If no latitude and longitude coordinates are provided, NowGo will attempt to geocode this location. |
geocode | boolean, optional | An explicit request to the system to attempt to geocode the location, overwriting any existing latitude and longitude coordinates. If set to true, NowGo will attempt to geocode this location, if set to false, no attempt will be made. If no value is passed, the system will only geocode if no valid coordinates were passed in. |
type | string, optional | Optional type of this location. Displayed in the dashboard. |
data | json, optional | Custom data to attach to this location. |
display_label | string, optional | Optional, four-character maximum label attached to this location which is used as a visual identifier in the dashboard. |
update_open_stops | boolean, optional | If true , updates to this location will also be applied to open stops and plan stops. |
Retrieve a location
Example Request (using id)
# curl https://api.nowgo.io/v0/locations/{id} \
-u :{auth_token}
Example Request (using ext_ref)
# curl https://api.nowgo.io/v0/locations/ext-ref/{ext_ref} \
-u :{auth_token}
Location objects can be retrieved using their ids or external references.
Path Parameters | ||
---|---|---|
id | string | The id of the location to be retrieved. |
ext_ref | string | External reference of the location to be retrieved. |
Response
Returns a location object if the request is valid.
Location Groups
The Location Group object
You can read more about Location Groups in Further Concepts.
Example Response
{
"id": "321",
"name": "Port of Botany",
"ext_ref": "port-of-botany",
"time_cost_seconds": 1800
}
Attributes | ||
---|---|---|
id | string | |
ext_ref | string | External reference for the Location Group. |
name | string | The Location Group's human-readable name |
time_cost_seconds | integer | The total time to add when stops in the Location Group are performed, if any. |
Create a Location Group
Example Request
# curl https://api.nowgo.io/v0/location-groups \
-u :{auth_token} \
-d {body}
Example Body
{
"name": "Port of Botany",
"ext_ref": "port-of-botany",
"time_cost_seconds": 1800
}
Body Parameters | ||
---|---|---|
ext_ref | string, optional | External reference for the Location Group. |
name | string | The Location Group's human-readable name |
time_cost_seconds | integer, optional | The total time to add when stops in the Location Group are performed, if any. |
Response
Returns a Location Group object if creation was successful. Returns an error if something goes wrong.
Retrieve a Location Group
Example Request (using id)
# curl https://api.nowgo.io/v0/location-groups/{id} \
-u :{auth_token}
Example Request (using external reference)
# curl https://api.nowgo.io/v0/location-groups/ext-ref/{ext_ref} \
-u :{auth_token}
Location Group objects can be retrieved using their ids or external references.
Path Parameters | ||
---|---|---|
id | string | The id of the Location Group being retrieved. |
ext_ref | string | External reference of the Location Group being retrieved. |
Response
Returns a Location Group object if the request is valid.
Update a Location Group
Example Request (using id)
# curl https://api.nowgo.io/v0/location-groups/{id} \
-X PATCH \
-u :{auth_token} \
-d {body}
Example Request (using ext_ref)
# curl https://api.nowgo.io/v0/location-groups/ext-ref/{ext_ref} \
-X PATCH \
-u :{auth_token} \
-d {body}
Location Groups can be modified using PATCH. They can be referred to using either an id or an external reference. See above for request body examples.
Path Parameters | ||
---|---|---|
id | string | The id of the Location Group being updated. |
ext_ref | string | External reference of the Location Group being updated. |
Body Parameters | ||
---|---|---|
ext_ref | string, optional | External reference for the Location Group. Location Group ext_ref s are mutable, unlike their equivalents in other objects. |
name | string, optional | The Location Group's human-readable name |
time_cost_seconds | integer, optional | The total time to add when stops in the Location Group are performed, if any. |
Retrieve all Location Groups
Example Request
# curl https://api.nowgo.io/v0/location-groups \
-u :{auth_token}
Example Response
[
{
"id": "182",
"ext_ref": "depot_1",
"name": "Depot 1",
"time_cost_seconds": 300
},
{
"id": "183",
"ext_ref": "depot_2",
"name": "Depot 2",
"time_cost_seconds": 800
}
]
Annotations
The annotation type object
Example object
{
"id": "17",
"name": "Comments",
"ext_ref": "driver-comments"
}
You can read more about annotations in Further Concepts.
Attributes | ||
---|---|---|
id | string | Id of this annotation type. |
name | string | Name of this annotation type. |
ext_ref | string | External reference for the annotation type. |
Create an annotation type
Example Request
# curl https://api.nowgo.io/v0/annotations \
-u :{auth_token} \
-d {body}
Example Body
{
"name": "Comments",
"ext_ref": "driver-comments"
}
Body Parameters | ||
---|---|---|
name | string | Name of this annotation type. |
ext_ref | string, optional | External reference for the annotation type. |
Response
Returns an annotation type object if creation was successful.
Retrieve annotation types
Example Request
# curl https://api.nowgo.io/v0/annotations \
-u :{auth_token}
Example Response
[
{
"id": "17",
"name": "Comments",
"ext_ref": "driver-comments"
},
{
"id": "18",
"name": "Waiting Time",
"ext_ref": "waiting"
}
]
Retrieves a list of all the annotation types that have been created.
Attributes | ||
---|---|---|
id | string | Id of this annotation type. |
name | string | Name of this annotation type. |
ext_ref | string | External reference for the annotation type. |
Response
Returns a list of annotation type objects belonging to this organisation.
Retrieve job annotation values
Example Request (using id)
# curl https://api.nowgo.io/v0/jobs/{job_id}/annotations \
-u :{auth_token}
Example Request (using external reference)
# curl https://api.nowgo.io/v0/jobs/ext-ref/{job_ext_ref}/annotations \
-u :{auth_token}
Example Response
[
{
"field_type_id": "17",
"field_type_ext_ref": "depot-safety",
"field_name": "Depot Safety",
"value": "All drivers must wear safety gear on site."
},
{
"field_type_id": "18",
"field_type_ext_ref": "dispatch-notes",
"field_name": "Instructions",
"value": "Leave package somewhere safe. Signature not required."
},
{
"field_type_id": "19",
"field_type_ext_ref": "driver-notes",
"field_name": "Driver Notes",
"value": null
}
]
Retrieves the annotations attached a job.
Path Parameters | ||
---|---|---|
job_id | string | Id of the job which is being modified. |
job_ext_ref | string | External reference of the job which is being modified. |
Body Parameters | ||
---|---|---|
field_type_id | string, optional | Id of the annotation type which is being set. |
field_type_ext_ref | string, optional | External reference for the annotation type. |
field_name | string | Name of field. |
value | string | Text which is populated for this field in this job. If set to null, this will clear this field for this job. |
Response
If a valid job is provided, a list of job annotation values are returned, showing the details of the annotation type and its value.
Workflow completions
The workflow completion object
You can read more about workflow completions in Further Concepts.
Example object
{
"id": "434454925375290842",
"driver_id": "384721",
"driver_ext_ref": "driver-1",
"device_id": "837201",
"workflow_type": "onboard",
"is_successful": true,
"device_completion_id": "ef061829-13f9-47e9-3b69-bda09322926d",
"time": "2021-08-118T21:30:21.133Z",
"latitude": -33.8925275,
"longitude": 151.2492009,
"location_time": null,
"custom_data": {
"lorem": "ipsum",
"dolor": "sit amet",
"consectetur": "adipiscing elit"
},
"subject_article_ids": ["37489", "98347"],
"attachments": [
{
"id": "356",
"label": "POD",
"tag": "photo",
"media_type": "image/png"
},
{
"id": "362",
"label": "Customer Signature",
"tag": "signature",
"media_type": "application/pdf"
}
],
"attachment_ids": ["356", "362"],
"outcome": "onboard",
"subject_articles": [{}],
"subject_consignments": [{}],
"stop_completions": [{}],
"shift_id": "00000000-0000-0000-0000-000000000001"
}
Attributes | ||
---|---|---|
id | string | |
driver_id | string | Id of the driver that completed the workflow. |
driver_ext_ref | string | External reference of the driver that completed the workflow. |
device_id | string | Id of the device used to complete the workflow. |
workflow_type | string | Type of workflow completed. |
is_successful | boolean | Indicates whether or not the workflow outcome was successful. |
device_completion_id | string | Local device id for the workflow completion. |
time | timestamp | Time that this workflow completion was created at. |
latitude | double | Latitude of the location. |
longitude | double | Longitude of the location. |
location_time | timestamp | Time at the location where the workflow completion was created. |
custom_data | json | Custom data to attach to the workflow completion. |
subject_article_ids | string list | Id list of subject articles. |
attachments | File list | Attachments for the workflow completion. |
attachment_ids | string list | Attachment ids for the workflow completion. |
outcome | string | Outcome of the workflow completion. |
subject_articles | article object list | Subject articles for the workflow completion. |
subject_consignments | consignment object list | Subject consignments for the workflow completion. |
stop_completions | stop completion object list | Stop completions for the workflow completion. |
shift_id | string | Id of the shift the workflow was completed in. |
Retrieve a workflow completion
Example request
$ curl https://api.nowgo.io/v0/workflow-completions/{id} \
-u :{auth_token}
Response
Returns a workflow completion object if creation was successful. Returns an error if something goes wrong.
Create a workflow completion
Example request
$ curl https://api.nowgo.io/v0/workflow-completions \
-u :{auth_token} \
-d {body}
Example body
{
"driver_ext_ref": "driver-1",
"workflow_type": "onboard",
"is_successful": true,
"time": "2021-08-18T21:30:21.133Z",
"latitude": -33.8925275,
"longitude": 151.2492009,
"stop_completions": {},
"custom_data": {
"lorem": "ipsum",
"dolor": "sit amet",
"consectetur": "adipiscing elit"
},
"subject_article_ids": ["37489", "98347"],
"attachments": [{}],
"shift_id": "00000000-0000-0000-0000-000000000001",
"outcome": "onboard"
}
Body Parameters | ||
---|---|---|
driver_id | string | Id of the driver that completed the workflow. |
driver_ext_ref | string | External reference of the driver that completed the workflow. |
Only one of driver_id and driver_ext_ref should be supplied. If both are supplied, the value of driver_id will be used. |
||
time | timestamp | Time that this workflow completion was created at. |
workflow_type | string, optional | Type of workflow completed. Accepted values are deliver , pickup , transfer , onboard , offboard , and observe . |
is_successful | boolean, optional | Indicates whether or not the workflow outcome was successful. |
latitude | double, optional | Latitude of the location. |
longitude | double, optional | Longitude of the location. |
custom_data | json, optional | Custom data to attach to the workflow completion. |
subject_article_ids | string list, optional | Id list of subject articles. |
attachments | file list, optional | Attachments for the workflow completion. |
shift_id | string | Id of the shift the workflow was completed in. |
outcome | string, optional | Outcome of the workflow completion. |
stop_completions | stop completion object list | Stop completions for the workflow completion. |
Response
Returns a workflow completion object if creation was successful. Returns an error if something goes wrong.
Users
The user object
Example object
{
"id": "23433",
"email": "user@premonition.io",
"enabled": true,
"name": "Example User",
}
The User object represents a dashboard user.
Attributes | ||
---|---|---|
id | string | ID of the user. |
string | User's email. | |
enabled | boolean | true if the user is enabled, false otherwise. Disabled users can't log in or interact with the system. |
name | string | Name of the user. |
Create a user
Example Request
# curl https://api.nowgo.io/v0/users \
-u :{auth_token} \
-d {body}
Example Body
{
"email": "user@premonition.io",
"password": "examplepassword",
"enabled": true,
"name": "Example User",
"permissions": {
"is_admin": false,
"roles": [
{
"id": "123",
"provided_channels": ["3414"],
"provide_all_channels": false
}
]
}
}
Body Parameters | ||
---|---|---|
string | Email to set for the user. | |
password | string, optional | Password to set for the user. |
enabled | boolean | true if the user is enabled, false otherwise. Disabled users can't log in or interact with the system. |
name | string, optional | Name of the user. |
permissions | optional | Permissions to assign to the user. |
is_admin | boolean, optional | If true , the created user will be an administrator. Defaults to false . |
roles | Roles to assign to the user. | |
id | string | ID of the role to be assigned. |
provided_channels | string list, optional | List of channels in which to assign the role. |
provide_all_channels | boolean, optional | If true , assigns the role in all channels. Defaults to false . |
Response
Returns a user if creation was successful. Returns an error if something goes wrong.
Webhooks
NowGo can send webhooks to notify external services of events.
Example: Shift webhook
A shift is updated, and a
POST
request is sent to all registered webhooks with the following payload:
{
"type": "shift",
"data": {
"id": "df8af3e7-1d1a-4ef7-ae91-32276fc89dc9",
"time_window_start": "2016-04-01T13:15:00Z",
"time_window_end": "2016-04-01T17:00:00Z",
"driver_id": "432",
"planned_events": [],
"jobs": []
},
"change_sequence_id": 8225
}
When a webhook is triggered, NowGo sends a POST
request to a webhook URL designated by the user. The body of this POST request will contain a JSON object including:
- A short string identifying what type of resource has been updated
- The updated resource
- (Optional) The change sequence ID of the update
Currently, webhooks can be sent after the following events:
Event | Webhook Type |
---|---|
Changes to shifts | shift |
Changes to jobs | job |
Changes to stops | stop |
Stop completions | completion |
Messages sent from the driver app | message |
Changes to driver location or stop ETAs | eta |
Custom fields added to jobs from the driver app | job_custom_field |
Changes to consignments | consignment |
Workflow completions | workflow_completion |
Chat messages are sent | chat_message |
Changes to files | file |
Stop acknowledgements occur | stop_acknowledgement |
Premonition is able to add multiple webhooks to your organisation, and to filter the type of events that are delivered. In future, we will have UI and API access to manage webhooks.
Delivery and retries
When webhook messages are received, your server is expected to send a response with the status 200 Ok
. This indicates that the message had been received and processed correctly.
A webhook message is considered unsuccessful if:
- the server was unreachable, or
- the server responded with something other than
200 Ok
When a webhook message isn't received successfully, NowGo will attempt to send it again at a later time. We apply an exponential backoff over the first hour, and then retry hourly for up to three days. This means that when messages encounter transient failures you will still receive information in a timely fashion, but if more serious problems have occurred we avoid overloading the receiving system.
Claim-check messages
Example: A claim-check webhook payload
{
"message_type": "claim-check",
"message_data": {
"message_id": "df8af3e7-1d1a-4ef7-ae91-32276fc89dc9",
"access_token": "32276fc89dc9",
"available_until": "2021-02-01T17:00:00Z"
}
}
NowGo supports sending webhooks in several different ways - via HTTPS, AWS SQS, AWS SNS, and Azure EventHub. These options make integration development more straightforward.
Some services, however, have limitations on the size of message they can accept. For example: - AWS SQS is limited to messages of 256KB or less. - Azure EventHub is limited to messages of 1MB or less.
Sometimes, NowGo produces webhook messages that are larger than these services will accept. This leads to failed deliveries and missed messages.
Example Request
# curl https://api.nowgo.io/v0/webhook-messages/{message_id}/claim-check?access_token={access_token} \
-u :{auth_token}
To address this issue, NowGo offers claim-check messages. Instead of sending the message itself, each webhook contains the information required to fetch the message from the NowGo API.
The response from the NowGo API will have the same body as the original webhook message.
After a claim-check is sent, the original message will be available via the API for at least 72 hours.
You can read more about the claim-check pattern here.
Configuring claim-check messages
Using claim-check messages means we can work with the size restrictions of several convenient transports. It does, however, place an additional maintenance burden on integrators and will result in increased latency for large messages.
If you're setting up an integration that may need to rely on claim-check messages, you'll need to implement a mechanism to recognise when a message needs to be fetched, and to do so. If you don't often have oversize messages you might only need to use claim-check messages occasionally, and so might not have a well exercised implementation.
To help ensure that claim-check messages are handled properly, NowGo offers a mechanism that can cause some or all messages to a particular webhook to be claim-check messages. We suggest making half of all messages claim-check during development, and then leaving claim-check messages enabled for a small fraction of messages in production.
For more information on configuring claim-check messages, see configuring webhooks.
Reliability for claim-check messages
claim-check messages are considered delivered after a success response is received for the original webhook. It's important, therefore, that the claim-check is stored durably by your system until you are able to fetch the message. This is straightforward when messages are delivered directly to a queue, as in the original use-case that necessitates claim-check messages.
ETA Webhooks
Example Message
A driver's location is updated, and a
POST
request is sent to all registered webhooks with the following payload:
{
"type": "eta",
"data": {
"driver_id": "4321",
"driver_ext_ref": "driver91",
"time": "2017-01-01T05:24:41Z",
"latitude": -33.8826164,
"longitude": 151.2043932,
"shifts": [
{
"id": "b836dda5-a973-4413-a8c2-c5f95cca16e6",
"ext_ref": "883GFz",
"version": 34,
"stops": [
{
"id": "5a753188-1d17-4fd8-baad-e3546f546b16",
"ext_ref": "STP323",
"version": 7,
"eta": "2017-01-01T05:31:30Z"
},
{
"id": "64a68e4c-9b11-4975-98bb-303a6cb64f5d",
"ext_ref": "STP324",
"version": 2,
"eta": "2017-01-01T05:40:51Z"
}
]
}
]
}
}
A key feature of the NowGo Driver App is location tracking, which gives access to the driver's travel history and to real-time ETA estimation. When the system receives updated information from a driver, any webhooks configured to receive ETA updates will be sent a message containing the driver's updated location and an ETA for each affected stop.
Attributes | |
---|---|
time | When the driver was at this location. This may be earlier than the current time, due to the Driver App delaying location updates. |
shifts | Shifts that contain stops assigned to the driver that have an updated ETA due to new information. Only shifts within a 12-hour window before or after the time of the location change are considered. |
shifts.stops.eta | Updated expected time-of-arrival for the stop. |
Configuring Webhooks
It is possible to create and modify webhook configurations through the NowGo API. You can modify the endpoint or URL, credentials, the protocol type, and the specific messages each webhook should receive.
The Webhook Configuration object
Example Webhook Configuration (HTTP configuration)
Example object with message types excluded for brevity.
{
"id": "43",
"endpoint": "https://webhook.nowgo.io/receive",
"protocol_type": "http"
}
Example Webhook Configuration (AWS SQS configuration)
Example object with message types excluded for brevity.
{
"id": "43",
"endpoint": "https://sqs.ap-southeast-2.amazonaws.com/production/receive",
"protocol_type": "aws/sqs",
"aws_access_key_id": "AAAAABBBB999999",
"aws_region": "ap-southeast-2"
}
Example Webhook Configuration (with claim-check messaging)
Example object with message types excluded for brevity.
{
"id": "43",
"endpoint": "https://sqs.ap-southeast-2.amazonaws.com/production/receive",
"protocol_type": "aws/sqs",
"aws_access_key_id": "AAAAABBBB999999",
"aws_region": "ap-southeast-2",
"claim_check_allowed": "true",
"claim_check_probability_threshold": 0.05
}
Attributes | ||
---|---|---|
id | string | |
endpoint | string | The target endpoint or URL to which the outgoing webhook will be sent to. |
protocol_type | string | Indicates the type of endpoint the webhook will be sent to. For example, to Amazon SQS, use aws/sqs . Defaults to http . See below for a list of supported providers. |
aws_access_key_id | string | Access key ID for Amazon Web Services. Must be provided if protocol_type is an AWS configuration. |
aws_secret_access_key | string | Secret access key for Amazon Web Services. Must be provided if protocol_type is an AWS configuration. This is an input only field and will not be populated in response payloads. |
aws_region | string | The AWS region string, such as ap-southeast-2 . Must be provided if protocol_type is an AWS configuration. |
claim_check_allowed | boolean | If true, allows this webhook to send claim-check messages if messages are too large. |
claim_check_probability_threshold | number | The proportion of messages which should be sent as claim-check messages regardless of message size, as a unit interval (0 <= X < 1 ). |
claim_check_all_messages | boolean | Forces this webhook to send all messages as claim-check messages. |
sync_stops | boolean | Notify for stop events. |
sync_jobs | boolean | Notify for job events. |
sync_shifts | boolean | Notify for shift events. |
sync_stop_completions | boolean | Notify for stop completion events. |
sync_etas | boolean | Notify for ETA events. |
sync_workflow_completions | boolean | Notify for workflow completion events. |
sync_consignments | boolean | Notify for consignment events. |
sync_chat_messages | boolean | Notify for chat message events. |
sync_stop_acknowledgements | boolean | Notify for stop acknowledgement events. |
sync_breaks | boolean | Notify for break events. |
sync_break_completions | boolean | Notify for break completion events. |
sync_files | boolean | Notify for file events. |
Accepted Protocol Types | |
---|---|
http |
(default) Send via HTTP/S. |
aws/sqs |
Amazon Web Services Simple Queue Service |
aws/sns |
Amazon Web Services Simple Notification Service |
azure/event_hub |
Microsoft Azure Event Hub |
Create a webhook configuration
When creating a webhook configuration, omitted message types will default to false
.
Example Request
# curl https://api.nowgo.io/v0/webhook-configs \
-u :{auth_token} \
-d {body}
Example Body
{
"endpoint": "https://webhook.nowgo.io/new/receiver",
"protocol_type": "http",
"sync_stops": "true",
"sync_shifts": "true",
"sync_breaks": "true"
}
Parameters | ||
---|---|---|
endpoint | string | The target endpoint or URL to which the outgoing webhook will be sent to. |
protocol_type | string | Indicates the type of endpoint the webhook will be sent to. For example, to Amazon SQS, use aws/sqs . Defaults to http . See below for a list of supported providers. |
aws_access_key_id | string, optional | Access key ID for Amazon Web Services. Must be provided if protocol_type is an AWS configuration. |
aws_secret_access_key | string, optional | Secret access key for Amazon Web Services. Must be provided if protocol_type is an AWS configuration. This is an input only field and will not be populated in response payloads. |
aws_region | string, optional | The AWS region string, such as ap-southeast-2 . Must be provided if protocol_type is an AWS configuration. |
claim_check_allowed | boolean, optional | If true, allows this webhook to send claim-check messages if messages are too large. Defaults to false . |
claim_check_probability_threshold | number, optional | The proportion of messages which should be sent as claim-check messages regardless of message size, as a unit interval (0 <= X < 1 ). |
claim_check_all_messages | boolean, optional | Forces this webhook to send all messages as claim-check messages. Defaults to false . |
sync_stops | boolean, optional | Notify for stop events, defaults to false . |
sync_jobs | boolean, optional | Notify for job events, defaults to false . |
sync_shifts | boolean, optional | Notify for shift events, defaults to false . |
sync_stop_completions | boolean, optional | Notify for stop completion events, defaults to false . |
sync_etas | boolean, optional | Notify for ETA events, defaults to false . |
sync_custom_events | boolean, optional | Notify for custom events, defaults to false . |
sync_workflow_completions | boolean, optional | Notify for workflow completion events, defaults to false . |
sync_consignments | boolean, optional | Notify for consignment events, defaults to false . |
sync_chat_messages | boolean, optional | Notify for chat message events, defaults to false . |
sync_stop_acknowledgements | boolean, optional | Notify for stop acknowledgement events, defaults to false . |
sync_breaks | boolean, optional | Notify for break events, defaults to false . |
sync_break_completions | boolean, optional | Notify for break completion events, defaults to false . |
sync_files | boolean, optional | Notify for file events, defaults to false . |
Response
Returns a webhook configuration object if creation was successful. Returns an error if something goes wrong.
Retrieve a webhook configuration
Example Request
# curl https://api.nowgo.io/v0/webhook-configs/{id} \
-u :{auth_token}
Webhook configuration objects can be retrieved using their id.
Parameters | ||
---|---|---|
id | string | The id for the webhook configuration being retrieved. |
Response
Returns a webhook configuration object if the request is valid.
Example Response (HTTP configuration)
Example response with message types excluded for brevity.
{
"id": "43",
"endpoint": "https://webhook.nowgo.io/receive",
"protocol_type": "http"
}
Update a webhook configuration
Example Request
# curl https://api.nowgo.io/v0/webhook-configs/{id} \
-u :{auth_token} \
-d {body}
Example Body
{
"endpoint": "https://webhook.nowgo.io/new/receiver",
"protocol_type": "http"
}
Applies an update to the given webhook configuration. Any parameters set to null
in the request will be cleared if valid. Any parameters not passed in the request will remain unchanged. You can read more about the semantics of PATCH in updating resources.
Parameters | ||
---|---|---|
endpoint | string | The target endpoint or URL to which the outgoing webhook will be sent to. |
protocol_type | string | Indicates the type of endpoint the webhook will be sent to. For example, to Amazon SQS, use aws/sqs . Defaults to http . See below for a list of supported providers. |
aws_access_key_id | string | Access key ID for Amazon Web Services. Must be provided if protocol_type is an AWS configuration. |
aws_secret_access_key | string | Secret access key for Amazon Web Services. Must be provided if protocol_type is an AWS configuration. This is an input only field and will not be populated in response payloads. |
aws_region | string | The AWS region string, such as ap-southeast-2 . Must be provided if protocol_type is an AWS configuration. |
claim_check_allowed | boolean | If true, allows this webhook to send claim-check messages if messages are too large. |
claim_check_probability_threshold | number | The proportion of messages which should be sent as claim-check messages regardless of message size, as a unit interval (0 <= X < 1 ). |
claim_check_all_messages | boolean | Forces this webhook to send all messages as claim-check messages. |
sync_stops | boolean | Notify for stop events. |
sync_jobs | boolean | Notify for job events. |
sync_shifts | boolean | Notify for shift events. |
sync_stop_completions | boolean | Notify for stop completion events. |
sync_etas | boolean | Notify for ETA events. |
sync_workflow_completions | boolean | Notify for workflow completion events. |
sync_consignments | boolean | Notify for consignment events. |
sync_chat_messages | boolean | Notify for chat message events. |
sync_stop_acknowledgements | boolean | Notify for stop acknowledgement events. |
sync_breaks | boolean | Notify for break events. |
sync_break_completions | boolean | Notify for break completion events. |
sync_files | boolean | Notify for file events. |
Response
Returns a webhook configuration object if update was successful. Returns an error if something goes wrong.
Delete a webhook configuration
Example Request
# curl https://api.nowgo.io/v0/webhook-configs/{id} \
-u :{auth_token} \
-X DELETE
Webhook configuration objects can be deleted using their id.
Parameters | ||
---|---|---|
id | string | The id for the webhook configuration being deleted. |
Response
Returns an archived webhook configuration object if delete was successful. Returns an error if something goes wrong.
Restore a webhook configuration
Example Request
# curl https://api.nowgo.io/v0/webhook-configs/{id}/restore \
-u :{auth_token} \
-X POST
Webhook configuration objects can be restored using their id.
Parameters | ||
---|---|---|
id | string | The id for the webhook configuration being restored. |
Response
Returns an restored webhook configuration object if restoration was successful. Returns an error if something goes wrong.
List webhook configurations
Example Request
# curl https://api.nowgo.io/v0/webhook-configs \
-u :{auth_token}
Response
Returns a list of webhook configuration objects if the request is valid.
Example Response
Example response with message types excluded for brevity.
{
"webhook_configs": [
{
"id": "43",
"endpoint": "https://sqs.ap-southeast-2.amazonaws.com/production/receive",
"protocol_type": "aws/sqs",
"aws_access_key_id": "AKIAAAAAABBBB999999",
"aws_region": "ap-southeast-2"
},
{
"id": "44",
"endpoint": "https://sqs.ap-southeast-2.amazonaws.com/production/receive-2",
"protocol_type": "aws/sqs",
"aws_access_key_id": "AKIAAAAAABBBB999998",
"aws_region": "ap-southeast-2"
}
]
}
Example Usage
In this section, we will illustrate how to retrieve webhook configurations, update their access keys, and check that the update succeeded.
# Retrieve existing webhook configurations
> curl https://api.nowgo.io/v0/webhook-configs \
-u :{auth_token}
> {
"webhook_configs": [
{
"id": "43",
"endpoint": "https://sqs.ap-southeast-2.amazonaws.com/production/receive",
"protocol_type": "aws/sqs",
"aws_access_key_id": "AKIAAAAAABBBB999999",
"aws_region": "ap-southeast-2"
}
]
}
# Update AWS access keys
> curl https://api.nowgo.io/v0/webhook-configs/43 \
-u :{auth_token} \
-d {
"aws_access_key_id": "AKIAEEEEEFFFF222222",
"aws_secret_access_key": "CCCCCDDDD111111",
}
> {
"id": "43",
"endpoint": "https://sqs.ap-southeast-2.amazonaws.com/production/receive",
"protocol_type": "aws/sqs",
"aws_access_key_id": "AKIAEEEEEFFFF222222",
"aws_region": "ap-southeast-2"
}
# Check to see update has applied appropriately
> curl https://api.nowgo.io/v0/webhook-configs/43 \
-u :{auth_token}
> {
"id": "43",
"endpoint": "https://sqs.ap-southeast-2.amazonaws.com/production/receive",
"protocol_type": "aws/sqs",
"aws_access_key_id": "AKIAEEEEEFFFF222222",
"aws_region": "ap-southeast-2"
}
Integration
Sometimes it is useful for an external system to push information directly to NowGo. An example is an integration with an existing dispatch solution. NowGo can be used to monitor the current allocation of work and suggest improvements while leaving the final decision making to the existing system. This allows drivers to use the NowGo Driver Application by augmenting, rather than replacing, an existing logistics solution.
External versions
Two conflicting requests
curl https://api.nowgo.io/v0/shifts/abc \
-X PUT \
-d '["321"]'
curl https://api.nowgo.io/v0/shifts/def \
-X PUT \
-d '["321"]'
When an authoritative external system wants to push information into NowGo, the ext_version
field is used to help control the effects of concurrent changes in information.
Each channel has an ext_version
field, used to ensure that updates are applied in the intended order. In the two requests to the right, without an external source of information, the system is unable to determine where the stop should be placed. One option would be to use a 'last write wins' approach, but this does not provide sufficient control of the effects of concurrency. At present, the value of ext_version
must be a 64-bit number.
Nowgo-Ext-Version
headers
Requests using ext_version headers
curl https://api.nowgo.io/v0/shifts/abc \
-X PUT \
-H 'Nowgo-Ext-Version: 1' \
-d '["321"]'
curl https://api.nowgo.io/v0/shifts/def \
-X PUT \
-H 'Nowgo-Ext-Version-If-Match: 1' \
-H 'Nowgo-Ext-Version: 2' \
-d '["321"]'
In the second example, the requests are using Nowgo-Ext-Version
headers. The first header is Nowgo-Ext-Version
, which sets the ext_version
of the channel if the request is successfully completed. The second is the Nowgo-Ext-Version-If-Match
header, which will only apply an update if the channel has a matching ext_version
.
Handling a mismatched ext_version
Requests with mismatched ext_versions
curl https://api.nowgo.io/v0/shifts/abc \
-X PUT \
-H 'Nowgo-Ext-Version: 50' \
-d '["321"]'
< HTTP/1.1 200 Ok
curl https://api.nowgo.io/v0/shifts/def \
-X PUT \
-H 'Nowgo-Ext-Version-If-Match: 99' \
-H 'Nowgo-Ext-Version: 100' \
-d '["321"]'
< 412 Precondition Failed
If a request is received with an ext_version
that does not match the current ext_version for the channel the request will be refused with a 412 Precondition Failed
response.
Managing ext_version
Request to update a channel
curl https://api.nowgo.io/v0/channels/1234
-X PATCH
-d '{"ext_version": 1}'
As ext_version
is a property of a channel, you can manage its state with the channels API. This allows you to reset the channel ext_version
to a known value.
Files
A file consists of two parts, specifically:
- metadata describing the file,
- the contents of the file.
Creating a file is a two-step process of first creating the metadata and then using the resulting metadata id to upload the file's contents. This metadata id can then be used to retrieve both the file's full metadata as well as its contents.
Endpoints that support file attachments will provide an 'attachment_ids' field for attaching existing files, as well as an 'attachments' field for creating new file metadata (though uploading the contents of these files must still be performed via a separate request to the files endpoint).
The file metadata object
Example Response
{
"id": "85",
"label": "Customer Signature",
"tag": "customer_signature",
"media_type": "image/png",
"has_contents": "false"
}
Attributes | ||
---|---|---|
id | string | |
label | string | A human-readable label for the contents of the file. |
tag | string | A tag for the contents of the file. This field's purpose is to be parsed by programs that consume a file. |
media_type | string | The media_type of the file. This will be passed in the Content-Type header when the file's contents are fetched. |
has_contents | boolean | Whether the file's contents are available for download. |
Create metadata for a file
Example Request
# curl https://api.nowgo.io/v0/files \
-u :{auth_token} \
-d {body}
Example Body
{
"label": "Customer Signature",
"media_type": "image/png"
}
Parameters | ||
---|---|---|
name | string | The file's filename |
media_type | string | The media_type of the file. This will be passed in the Content-Type header when the file's contents are fetched. |
Response
Returns a file metadata object if creation was successful. Returns an error if something goes wrong.
Retrieve metadata for a file
Example Request
# curl https://api.nowgo.io/v0/files/{id} \
-u :{auth_token}
Example Response
{
"id": "2",
"label": "Invoice",
"media_type": "application/pdf",
"has_contents": true
}
Response
Returns a file metadata object if one exists with the request id. Returns an error if something goes wrong.
Upload contents for a file
Example Request
# curl https://api.nowgo.io/v0/files/{id}/contents \
-u :{auth_token} \
--data-binary "{file}"
Parameters | ||
---|---|---|
file | binary data | Contents of the file to be stored. |
Response
Returns a file metadata object if the upload was successful. Returns an error if something goes wrong.
Download contents for a file
Example Request
# curl https://api.nowgo.io/v0/files/{id}/contents -u :{auth_token}
Response
Returns a binary body containing the file's contents if they are available. Returns an error if something goes wrong. If a file is not yet available because it has not finished uploading, returns a 404 Not Found.
Solve Settings
NowGo is a general and versatile tool that can handle many different logistic needs. Sometimes, to realise the benefit of the system some configuration is needed.
Solve settings are used to change the behaviour of NowGo in relation to solving and planning. At this time solve settings aren't configurable via the API, but can be configured from the dashboard.
Managing solve settings
To change solve settings from the dashboard, use the "solve settings" button at the top right of a channel or plan.
Pressing the button opens the solve settings panel.
Allow depot mode
When is this setting useful?
Your logistic scenario has a single depot where all pickups or deliveries occur.
What does this setting change?
Solves should complete in less time, with better results. If depot mode isn't applicable to your scenario, applying this setting shouldn't have any impact.
Use minimum shifts
When is this setting useful?
You want to reduce or minimise the number of shifts used in your solution.
All the shifts in your scenario have the same time windows, capacities, attributes, vehicle types, and travel efficiencies.
What does this setting change?
NowGo will use less shifts where possible. Solves will take longer, and results may be less stable (i.e. stops may be reassigned more than in non "Use minimum shifts" solves).
Avoid eager pickups
When is this setting useful?
If you've got pickups and deliveries, and you'd rather drivers perform pickups later where possible without adding extra time.
For example, if your driver is picking up from a depot for multiple runs on the same day NowGo may instruct the driver to pick up freight for all runs during the first visit to the depot (vehicle capacity allowing, of course). This settings allows you to instruct NowGo to pick up the freight before each run if possible, instead of all at the start of the day.
What does this setting change?
Moves pickups as close to deliveries as possible, without adding more overall work or time for drivers.
Allow use of seed solve
When is this setting useful?
You're making small, incremental changes to a scenario and you want your solve results to be similar to those you started with.
What does this setting change?
Uses the current assignment of stops as a "seed" for solves. This means the solve starts with the existing solution and tries to improve on it, instead of starting from scratch. If the system isn't able to usefully use your current solution in solves, this setting will have no effect.
Notes
Using seed solve can make solves return faster, but can also result in less optimised solutions than a solve from scratch would.
Use fast seed solve
When is this setting useful?
You're using the "Allow use of seed solve" setting, and you're expecting to perform a large number of small solves.
For example, if you're assigning stops individually to drivers as they're created in your system, and don't allow sequencing or reassignment in solves.
What does this setting change?
This setting increases the weight given to the current solution, and decreases the overall time available to solve.
Notes
Using fast seed solve may make results even less optimised than seed solve, especially if the solution needs large changes.
Time allowance multiplier for fast seed solve
When is this setting useful?
You've applied the "Use fast seed solve" setting and would like your results to be slower but better optimised, or faster but less well optimised.
What does this setting change?
The amount of time spent in a fast seed solve. Higher numbers will lead to more time spent solving, and hopefully more optimised results.
Time allowance multiplier for all solves
When is this setting useful?
You'd like your solve results to be slower but better optimised, or faster but less well optimised.
If you're performing a large, one-off optimisation you can use this setting to get the best results possible by solving for a long period of time.
What does this setting change?
Increases or decreases the amount of time taken to solve. Less time taken means faster results, but more time taken means more optimised results.
Upcoming stop cutoff for optimisation
When is this setting useful?
You've got drivers performing work, and you don't want to change the stop they're headed to next.
What does this setting change?
Prevents NowGo from changing the immediately upcoming stops in a driver's shift.
For example, if "Upcoming stop cutoff for optimisation" is set to "3", the first three stops in each shift will never be changed by sequencing or optimisation.
Default job value
We'd recommend using Priorities instead of changing this setting.
When is this setting useful?
You've got jobs very far apart, and NowGo isn't assigning them.
What does this setting change?
Changes the amount of drive time that NowGo thinks is "worthwhile" to complete a job.
For example, if you've got a driver in Sydney and a job in Canberra, NowGo's optimisation may suggest that the job isn't worth completing. Increasing the "Default job value" increases the likelihood that the job will be "worth" completing.
Enable elastic time windows
This setting is on by default.
When is this setting useful?
Tries to schedule work to be completed late, rather than letting it be unassigned.
If you never want to plan for work to run late, and would rather work be unassigned instead, you should turn "Enable elastic time windows" off.
What does this setting change?
When "Enable elastic time windows" is on, work that can't be completed on time may still be assigned to a driver, and allowed to run late. The system will attempt to minimise the overall impact of any lateness, depending on job priority and other factors.
Maximum allowed lateness per stop
When is this setting useful?
If "Enable elastic time windows" is on, but you'd like to adjust how late a stop might be in the worst case.
What does this setting change?
Any stops that are later than this threshold will not be assigned to drivers, and will instead be dropped. The system will attempt to minimise the overall impact of any lateness, depending on job priority and other factors.
Global driver efficiency multiplier
When is this setting useful?
The drivers in your fleet are faster or slower than drivers in typical fleets.
What does this setting change?
Applies a scaling factor to drive time calculations in NowGo, which will also change ETAs. Higher numbers mean your drivers are assumed to travel faster than other areas.
Notes
There are several factors that might influence the speed of your drivers, including equipment and typical working environments. Drivers performing fewer stops over a wider area typically might have a faster typical travel speed than drivers in denser networks.
The "Ignore driver efficiencies" and "Ignore shift efficiencies" toggles can be used to ignore efficiencies applied to drivers and shifts, so that all the shifts in a scenario have a uniform efficiency.
"Default shift 'out of bed' cost"
When is this setting useful?
If you'd rather NowGo use fewer shifts but make drivers do more work, or use more shifts and make drivers do less work. If you're seeing some jobs left unassigned, when there's drivers with no stops assigned.
What does this setting change?
Changes the amount of work that is considered "enough" to add another shift to the scenario. Increasing this setting will make NowGo try to perform more work with current drivers before adding more.
Notes
The "Override individual values" toggle can be used to ignore 'out of bed' costs on individual shifts, and instead apply an overall 'out of bed' cost.
Guide: Using plans via the API
A plan is a copy of the world where you can safely experiment with changes and see the impacts they may have on your fleet. You can use plans to make and evaluate different decisions in a risk-free environment.
Overview
In this guide, we're going to make a new plan with a copy of an existing shift. We'll add some new stops to the plan, solve it, and inspect the results. Finally, we'll dispatch the plan so our changes take effect.
Prerequisites
To follow these steps you'll need API access to a NowGo organisation. Please see our API documentation for help getting started.
It's safest to use a sandbox organisation or a new channel when following these steps for the first time, to reduce the risk of accidental changes to live channels. You'll need to know the id of your channel, which you can see in the dispatch URL in the dashboard.
Before starting, we'll need a shift in our channel. You can create one via the API or with the dashboard. For these examples, we'll assume the shift has been created on the current date.
Environment Setup
To make the examples in this guide easy to copy and paste, we can do some environment setup. You'll need to replace the values
auth_token="<Your auth token here>"
channel_id="<Your channel_id here>"
Step 1: Create a plan
We'll create a plan from our channel using a window of time. Plans created in this way capture all the contents of the channel during a time window, without needing to specify things individually.
curl "https://api.nowgo.io/v0/channels/${channel_id}/plans" \
-u "${auth_token}": \
-d '{
"time_window_start": "'"$(date +%F)T00:00:00Z"'",
"time_window_end": "'"$(date +%F)T23:59:59Z"'"
}'
If the request works, you should see a response that includes an id and a list of shifts, as well as other data about your plan. If you navigate to https://dashboard.nowgo.io/plans/${plan_id}
, you should see your newly-created plan at the top of the list, and if you open it you should see your shift.
We'll save the plan id for later use.
plan_id="<Your plan_id here>"
Step 2: Add jobs and stops to the plan
Using the API, we'll add some jobs and stops to the plan. As we're creating these directly in the plan, they will only be visible in this plan unless we dispatch it or create them elsewhere. For this example, we'll create three jobs.
curl "https://api.nowgo.io/v0/plans/${plan_id}/jobs" \
-u "${auth_token}": \
-d '{
"stops": [
{
"time_window_start": "'"$(date +%F)T00:00:00Z"'",
"time_window_end": "'"$(date +%F)T23:59:59Z"'",
"service_time": "180",
"location": {
"address": "87 Pine St, Randwick NSW 2031"
}
}
]
}'
curl "https://api.nowgo.io/v0/plans/${plan_id}/jobs" \
-u "${auth_token}": \
-d '{
"stops": [
{
"time_window_start": "'"$(date +%F)T00:00:00Z"'",
"time_window_end": "'"$(date +%F)T23:59:59Z"'",
"service_time": "180",
"location": {
"address": "18 Marathon Rd, Darling Point NSW 2027"
}
}
]
}'
curl "https://api.nowgo.io/v0/plans/${plan_id}/jobs" \
-u "${auth_token}": \
-d '{
"stops": [
{
"time_window_start": "'"$(date +%F)T00:00:00Z"'",
"time_window_end": "'"$(date +%F)T23:59:59Z"'",
"service_time": "180",
"location": {
"address": "7 Ashton St, Queens Park NSW 2022",
"latitude": -33.872,
"longitude": 151.205
}
}
]
}'
If the requests complete successfully, you should see three unassigned jobs in your plan. If you don't see them straight away, you can refresh the page so that the data is up-to-date.
Step 3: Solve the plan
We'll trigger a full solve of the plan via the API, which should assign your stops to shifts. In this case, we expect all three jobs to be assigned to the shift in a sensible order.
In the request, we set the solve_profile_ext_ref
as full
so that NowGo is free to reassign and rearrange existing stops as well as assign our new ones.
curl "https://api.nowgo.io/v0/channels/${channel_id}/plans/${plan_id}/solves" \
-u "${auth_token}": \
-d '{"solve_profile_ext_ref": "full"}'
The request will return as soon as your solve is started, and contains an id for the solve as well as some other data. We can check what solves are in progress via the API.
curl "https://api.nowgo.io/v0/channels/${channel_id}/plans/${plan_id}/solves" \
-u "${auth_token}":
If the response is an empty list, your solve is complete. If everything is as expected, the dashboard should now show your stops assigned to the shift.
Step 4: Dispatch the plan
If we're happy with the contents of the plan, we can dispatch it so the changes in the plan take effect in the real-world. In the API, dispatching a plan is referred to as "merging" it.
curl "https://api.nowgo.io/v0/channels/${channel_id}/plans/${plan_id}/merge" \
-u "${auth_token}": \
-d "{}"
If the request is successful, you should now see your changes in the Dispatch view.
Next Steps
Experiment with the effects of other solve profiles on different scenarios. Several are available, and you can find more information in the Create a solve section.
Try making changes in Dispatch and in a plan at the same time, and merging using
allow_conflicts
so that changes in the plan override changes in the world. See the Merge a plan section for more information.