Time

GET /v1/analytics/time

Returns summary statistics (quantiles, mean, and median) for a delivery time metric at a specific building. The address is required.

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

Request

Query Parameters

Parameter	Type	Required?	Description
address	string	Yes	The building to analyze. Example: 123 Main St, San Francisco, CA 94105
metric	string	No	Which time metric to analyze. Default: handoverTime. Allowed values: handoverTime, totalTime, walkingTime, inBuildingTime, activeTime
quantiles	string	No	Comma-separated quantile values, each between 0 and 1 (exclusive). Default: 0.05,0.5,0.95. Max: 20. Example: 0.1,0.5,0.9
deliveryType	string	No	Comma-separated delivery type filter. Allowed values: doorstep, threshold, curbside, vehicle_handoff
timeFrame	string	No	Preset time window. Default: week. Allowed values: day, week, month, 3m, ytd, year, all
from	integer	No	Start time in epoch seconds. Overrides timeFrame. Must be ≤ to.
to	integer	No	End time in epoch seconds. Overrides timeFrame. Must be ≥ from.

Time Metrics

See Time Metrics in the reference for what each metric measures. All time values in the response are in seconds.

Example Request

curl "https://api.core.doorstep.ai/v1/analytics/time?address=123 Main St, San Francisco, CA 94105&metric=handoverTime" \
  -H "Authorization: Bearer $API_KEY"

Response

200

Statistical summary of the requested time metric for the building.

Response Body

Field	Type	Description
metric	string	The time metric analyzed.
count	integer	Number of sessions included in the summary.
median	number | null	Median value, in seconds. null if there are no sessions.
mean	number | null	Mean value, in seconds. null if there are no sessions.
quantiles	array of objects	One entry per requested quantile.
quantiles[].p	number	The quantile (between 0 and 1).
quantiles[].value	number | null	The metric value at that quantile, in seconds. null if there are no sessions.

Example Response

{
  "metric": "handoverTime",
  "count": 342,
  "median": 180,
  "mean": 195.5,
  "quantiles": [
    { "p": 0.05, "value": 45 },
    { "p": 0.5,  "value": 180 },
    { "p": 0.95, "value": 420 }
  ]
}

400

A required parameter is missing or invalid. For example, address was not provided.

{
  "status": 400,
  "code": "bad_request",
  "message": "Address is required"
}

401

The API key is missing or invalid.

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

500

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

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

Limits

• Max 20 quantiles per request.

Example Usage

A histogram of handoverTime reconstructed from the quantile response. Values are sampled from the inverse CDF defined by the returned quantiles.

Common Applications

• More efficient route planning for dispatchers
• Better stop time estimates
• Better ETA estimation for the customer
• More accurate delivery windows
• Verifying driver stop time during dispute resolution