Price a delivery

POST

/quotes

curl --request POST \
  --url https://api.govza.app/v1/delivery/quotes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "pickup": { "latitude": 43.342439, "longitude": 45.693597 }, "dropoffs": [ { "latitude": 43.320872, "longitude": 45.691756, "cargo_size": "M" }, { "latitude": 43.351021, "longitude": 45.69154, "cargo_size": "S" } ], "routing_mode": "sequential" }'

Returns the price, distance and duration for a trip without creating anything. Pass the returned quote_id to POST /orders to lock in these prices; quotes expire after five minutes, after which the order is re-priced at the current rate.

Authorizations

• apiKey

Request Body^required

Media typeapplication/json

Pricing needs coordinates and cargo size, and nothing else — no addresses and no contact details. You can price a basket before the customer has typed an address, and you never send us personal data for a call that has no use for it.

object

pickup

required

object

latitude

required

number

>= -90 <= 90

longitude

required

number

>= -180 <= 180

dropoffs

required

Array

>= 1 items <= 10 items

object

latitude

required

number

>= -90 <= 90

longitude

required

number

>= -180 <= 180

cargo_size

Overrides the request-level cargo_size for this stop.

string

Allowed values: S M L XL

cargo_size

Applies to every dropoff that does not set its own. Cargo size is priced per destination, so it changes the quote; GET /cargo-sizes lists what each size covers and adds.

string

default: S

Allowed values: S M L XL

routing_mode

sequential routes one chained trip through every dropoff in order. parallel prices each dropoff independently from the pickup.

string

default: sequential

Allowed values: parallel sequential

dropoff_order

The order the courier visits the dropoffs in. given, the default, keeps the order you sent. optimized reorders every dropoff into the shortest road route from the pickup, and the trip is priced along that route. optimized_keep_last does the same but keeps your last dropoff last. Your order stays when no other is shorter. Only for routing_mode: sequential; with parallel the request is refused.

string

default: given

Allowed values: given optimized optimized_keep_last

Example

{
  "pickup": {
    "latitude": 43.342439,
    "longitude": 45.693597
  },
  "dropoffs": [
    {
      "latitude": 43.320872,
      "longitude": 45.691756,
      "cargo_size": "M"
    },
    {
      "latitude": 43.351021,
      "longitude": 45.69154,
      "cargo_size": "S"
    }
  ],
  "routing_mode": "sequential"
}

Responses

200

The trip was priced.

Media typeapplication/json

object

success

boolean

data

object

quote_id

Pass to POST /orders to keep these prices.

string

price

Sum of every leg, each including its cargo surcharge.

number

distance

number

duration

number

expires_at

string format: date-time

dropoffs

One leg per dropoff, in your order. For sequential, each is the leg arriving at that dropoff from the stop visited before it.

Array<object>

object

route_id

string

distance

Metres.

number

duration

Seconds.

number

cargo_size

string

Allowed values: S M L XL

price

Route price for this leg plus its cargo surcharge.

number

cargo_surcharge

The part of price that is the cargo surcharge, as GET /cargo-sizes lists it for the tariff this leg was priced by. price minus cargo_surcharge is the distance price.

number

visit_order

Zero-based positions in your dropoffs array, in the order the courier visits them. Everything else stays in your order: quote legs, tracking_urls and index in PATCH.

Array<integer>

Example

{
  "data": {
    "dropoffs": [
      {
        "cargo_size": "S"
      }
    ],
    "visit_order": [
      2,
      0,
      1
    ]
  }
}

400

The payload was rejected. error.details is a JSON array of { field, message } covering every offending field, not just the first, so one response is enough to fix the request.

Media typeapplication/json

object

success

boolean

error

object

id

string

code

string

message

string

details

string

Example

{
  "success": false,
  "error": {
    "id": "validation.delivery_payload_invalid",
    "message": "dropoffs.0.address.latitude: latitude is required",
    "details": "[{\"field\":\"dropoffs.0.address.latitude\",\"message\":\"latitude is required\"}]"
  }
}

401

The key is missing, malformed, revoked, or its account can no longer create orders.

Media typeapplication/json

object

success

boolean

error

object

id

string

code

string

message

string

details

string

Example

{
  "success": false
}