Usage - GET

Retrieve a transaction usage report for your account over a date range, bucketed by a unit of time and service.

The report can be further filtered to a particular service or API key.

Resource URL

https://www.mapquestapi.com/account/v1/usage

https://www.mapquestapi.com/account/v1/usage/{key}

Resource Information

Response Formats	JSON
Authentication	Yes (Requires Key)
Rate Limited	No

Path Parameters

Path Parameter	Description	Required
key	When present, scopes the report to usage for this single key. Omit to report across all of the account's keys.	No

Request Parameters

Request Parameter	Description	Required
key	The API Key, which is needed to make requests to MapQuest services.	Yes
startDate	Start of the report window (inclusive), as an ISO 8601 date or date-time (e.g. 2024-01-01 or 2024-01-01T00:00:00Z). Dates without a time zone are interpreted as UTC.	Yes
endDate	End of the report window (exclusive). Must be after startDate.	Yes
timeUnit	The bucket size for each usage row. One of year, quarter, month, week, day, hour. Defaults to day. When hour is used, the window may not exceed 1 week.	No
service	Restrict the report to a single service (e.g. directions, geocoding). Other services may still be reported if they were invoked as a result of the requested service.	No

Service list
account
address
autosuggest
datamanager
datamanager.search
directions
directions.v2
geocoding
geocoding.v1
geolocation
logger
routing
search
search.v5
staticmap
traffic

Response Object

Field	Type	Description
consumerId	string	Identifier for the account the report was generated for.
key	string	The key the report was scoped to, if one was provided.
startDate	string	The start of the report window, echoed back.
endDate	string	The end of the report window, echoed back.
timeUnit	string	The bucket size used for the usage rows.
totals	object	Account-wide totals for the window.
totals.sum	number	The total transaction count across all services.
totals.services	object	A map of service name to its total transaction count for the window.
usage	array	Per-bucket usage rows, ordered by date descending.
usage[].date	string	The start of the time bucket (truncated to timeUnit).
usage[].service	string	The service the row's count applies to.
usage[].count	number	The transaction count for that service in that bucket.

Error Responses

Errors are returned as application/problem+json. Refer to the status codes page for more details.

Status	Description
400	Validation error. startDate/endDate are missing or malformed, startDate is not before endDate, timeUnit is unsupported, or an hour report exceeds the 1-week limit.
401	Missing or invalid consumer identity. The request could not be authenticated.
403	The report was scoped to a key the authenticated account does not own.
404	Consumer not found. No account matches the authenticated identity.
500	An internal error occurred. Please retry.

Example Requests

1. Usage for the directions service for every day of January 2026, across all keys.

curl -X GET 'https://www.mapquestapi.com/account/v1/usage' \
  --url-query 'startDate=2026-01-01' \
  --url-query 'endDate=2026-02-01' \
  --url-query 'timeUnit=day' \
  --url-query 'service=directions' \
  --url-query 'key=KEY'

2. Usage for your key <KEY-FILTER>, by week for January 2026, across all services.

curl -X GET 'https://www.mapquestapi.com/account/v1/usage/<KEY-FILTER>' \
  --url-query 'startDate=2026-01-01' \
  --url-query 'endDate=2026-02-01' \
  --url-query 'timeUnit=week' \
  --url-query 'key=KEY'

3. Usage by hour for your key <KEY-FILTER>, during the working hours of Aug 1st, 2026.

curl -X GET 'https://www.mapquestapi.com/account/v1/usage/<KEY-FILTER>' \
  --url-query 'startDate=2026-08-01T09:00:00-07:00' \
  --url-query 'endDate=2026-08-01T17:00:00-07:00' \
  --url-query 'timeUnit=hour' \
  --url-query 'key=KEY'

Example Response

200 OK

{
  "consumerId": "5b0598ee49391a30c3218ace",
  "startDate": "2024-01-01T00:00:00.000Z",
  "endDate": "2024-01-03T00:00:00.000Z",
  "timeUnit": "day",
  "totals": {
    "sum": 14245,
    "services": {
      "directions": 12463,
      "geocoding": 1782
    }
  },
  "usage": [
    {
      "date": "2024-01-02T00:00:00.000Z",
      "service": "directions",
      "count": 6232
    },
    {
      "date": "2024-01-02T00:00:00.000Z",
      "service": "geocoding",
      "count": 801
    },
    {
      "date": "2024-01-01T00:00:00.000Z",
      "service": "directions",
      "count": 6231
    },
    {
      "date": "2024-01-01T00:00:00.000Z",
      "service": "geocoding",
      "count": 981
    }
  ]
}

Scoped to a key

{
  "consumerId": "5b0598ee49391a30c3218ace",
  "key": "IL1deIyHyQA40WpeLeA1bIUXuvTwlGjo",
  "startDate": "2024-01-01T00:00:00.000Z",
  "endDate": "2024-01-03T00:00:00.000Z",
  "timeUnit": "day",
  "totals": {
    "sum": 0,
    "services": {}
  },
  "usage": []
}