Volume

GET /v1/analytics/volume

Returns the total delivery volume over a given time window. Volume is broken out by delivery type and includes an overall total. Optional interval parameter to observe volume over time.

Requires an API key sent as a Bearer token in the Authorization header.

Request

Query Parameters

Parameter	Type	Required?	Description
address	string	Optional	Filters volume to a specific address. Example: 123 Main St, San Francisco, CA 94105
driverID	string	Optional	Filters volume to sessions completed by a specific driver.
deliveryType	string	Optional	Comma-separated delivery type filter. Allowed values: doorstep, threshold, curbside, vehicle_handoff Example: doorstep,threshold
timeFrame	string	Optional	Preset time window. Default: week. Allowed values: day, week, month, 3m, ytd, year, all
interval	string	Optional	Length of each time interval. Default: none. Allowed values: none, hour, day, week, month
from	integer	Optional	Start time in epoch seconds. Overrides timeFrame. Must be ≤ to. Example: 1748390400
to	integer	Optional	End time in epoch seconds. Overrides timeFrame. Must be ≥ from. Example: 1748995200

Example Request

curl "https://api.core.doorstep.ai/v1/analytics/volume?address=123 Main St, San Francisco, CA 94105&deliveryType=doorstep,threshold&timeFrame=week" \
  -H "Authorization: Bearer $API_KEY"

Response

200

Delivery volume for the requested address.

Response Body

Field	Type	Description
total	integer	Total delivery count across all delivery types for the window.
series	array of objects	Breakdown by delivery type.
series[].timestamp	integer	Start of the interval if specified, in epoch seconds.
series[].key	string	The delivery type.
series[].count	integer	Delivery count for that delivery type.

Example Response

{
  "total": 115,
  "interval": "week",
  "from": 1704067200,
  "to": 1704153600,
  "series": [
    {
      "timestamp": 1704067200,
      "count": 45,
      "key": "doorstep"
    },
    {
      "timestamp": 1704067200,
      "count": 12,
      "key": "threshold"
    },
    {
      "timestamp": 1704153600,
      "count": 58,
      "key": "doorstep"
    }
  ]
}

400

Input parameters do not meet the required conditions

{
  "status": 400,
  "code": "bad_request",
  "message": "Invalid interval; allowed: none, hour, day, week, month"
}

401

The API key is missing or invalid.

{
  "status": 401,
  "code": "unauthorized",
  "message": "Token Invalid"
}

404

No building was found for the requested address.

{
  "status": 404,
  "code": "not_found",
  "message": "Building with the given address was not found"
}

500

Something went wrong on our end. Try the request again later.

{
  "status": 500,
  "code": "internal_server_error",
  "message": "Internal Server Error"
}

Example Usage

Common Applications

• Anomaly flagging for customer support agents
• Identify peak and low delivery windows