This API is under active development, and breaking changes may be made without warning. Have feedback or questions? Please let us know! Please note we have recently updated to `v2.0.0`, please update your requests accordingly.
Overview
In addition to being published and available for download, the data generated for analytics.usa.gov is also available via an API.
Please note we have recently updated to v2.0.0
, please update your requests accordingly.
The URL for the API is https://api.gsa.gov/analytics/dap/v2.0.0
, and it exposes 3 routes to query data:
/reports/<report name>/data
/agencies/<agency name>/reports/<report name>/data
/domain/<domain>/reports/<report name>/data
Getting Started
To begin using this API, you will need to register for an API Key. You can sign up for an API key below. After registration, you will need to provide this API key in the x-api-key
HTTP header with every API request.
HTTP Header Name | Description |
---|---|
x-api-key | API key from api.data.gov. For sample purposes, you can use DEMO_KEY as an API key. |
OpenAPI Specification File
You can view the full details of this API in the OpenAPI Specification file available here: Open API specification file for the Digital Analytics Program API
The Response
The response represents the rows in the data
array in the JSON reports that can be downloaded, or the rows in the CSV files that can be downloaded. They are returned as an array of JSON objects. Here is an example of one such object:
{
"id": 60716,
"report_name": "today",
"report_agency": "justice",
"date": "2017-04-07T14:00:00.000Z",
"visits": "4240",
"created_at": "2017-04-07T04:23:55.792Z",
"updated_at": "2017-04-07T04:23:55.792Z"
}
Note that is has the following properties:
id
: The primary key of the data pointreport_name
: The name of the data point’s reportreport_agency
: The name of the data point’s agencydate
: The data/time the data in the data point corresponds tovisits
: The requested visit data for the data point. This is shown as an example of possible data fields that will be included as siblings to the required properties above. Properties such as visits, browser, screen size, and so on, can be included depending on the report.
Querying reports
Reports can be queried by substituting <report name>
in the path with the name of the report.
The following reports can be queried using the API:
- download (example)
- traffic-source (example)
- device-model (example)
- domain (example)
- site (example)
- second-level-domain (example)
- language (example)
- os-browser (example)
- windows-browser (example)
- browser (example)
- windows-ie (example)
- os (example)
- windows (example)
- ie (example)
- device (example)
Filtering based on agencies
Reports can be queried by substituting <agency name>
in the path with the name of the agency. If the path without an agency name parameter is used, the reports correspond to government wide data.
The list of valid agency names includes:
- agency-international-development (example)
- agriculture (example)
- commerce (example)
- defense (example)
- education (example)
- energy (example)
- environmental-protection-agency (example)
- executive-office-president (example)
- general-services-administration (example)
- health-human-services (example)
- homeland-security (example)
- housing-urban-development (example)
- interior (example)
- justice (example)
- labor (example)
- national-aeronautics-space-administration (example)
- national-archives-records-administration (example)
- national-science-foundation (example)
- nuclear-regulatory-commission (example)
- office-personnel-management (example)
- postal-service (example)
- small-business-administration (example)
- social-security-administration (example)
- state (example)
- transportation (example)
- treasury (example)
- veterans-affairs (example)
Filtering by domain
For the site
, domain
, download
, and second-level-domain
reports you may use the domain
route, to only return results by domain.
Query params
The following query params are supported to work with the data:
limit
: Limit the number of data points that are rendered. The default is 1000 and the max is 10,000page
: Pages through the results. If the limit is set to1000
, usingpage=2
will render the 1001st through 2000th data point.after
: Limit the results to in dates on or after the date specified. ExpectsYYYY-MM-DD
.before
: Limit the results to in dates on or before the date specified. ExpectsYYYY-MM-DD
.
HTTP Response Codes
The API will return one of the following responses:
HTTP Response Code | Description |
---|---|
200 | Successful. Data will be returned in JSON format. |
400 | Bad request. Verify the query string parmaters that were provided. |
403 | API key is not correct or was not provided. |
4XX | Additional 400-level are caused by some type of error in the information submitted. |
Migrating from API V1 to API V2
Background
Analytics API V1 returns data from Google Analytics V3, also known as Universal Analytics (UA).
Google is retiring UA and is encouraging users to move to their new version Google Analytics V4 (GA4) in 2024.
Analytics API V2 returns data from GA4.
Migration details
Requests
The Analytics API endpoints are the same between V1 and V2, the only difference for API requests is the API version string.
Responses
Response data is slightly different in Analytics API V2. This change is due to the data provided by Google Analytics. Some data fields were retired in GA4, and some other useful data fields were added. The changes follow:
Deprecated fields
- browser_version
- has_social_referral
- exits
- exit_page
New fields
bounce_rate
The percentage of sessions that were not engaged. GA4 defines engaged as a session that lasts longer than 10 seconds or has multiple pageviews.
file_name
The page path of a downloaded file.
language_code
The ISO639 language setting of the user’s device. e.g. ‘en-us’
session_default_channel_group
An enum which describes the session. Possible values:
‘Direct’, ‘Organic Search’, ‘Paid Social’, ‘Organic Social’, ‘Email’, ‘Affiliates’, ‘Referral’, ‘Paid Search’, ‘Video’, and ‘Display’
Contact Us
To suggest a feature or ask for help, please file an issue in our project repository.