analytics.usa.gov API | GSA Open Technology
analytics.usa.gov API
Overview
Getting started
Common use cases
Find data for a date range
Find data for a particular domain name
Find data for a particular agency
Authentication
Endpoints
API versions
/reports
Path structure
Example
/agencies
Path structure
Example
/domain
Path structure
Example
Query params
Response structure
HTTP response codes
OpenAPI specification file
Available reports
Available agencies
Migrating from API V1 to API V2
Background
Requests
Responses
Deprecated fields from V1
New fields in V2
file_name
language_code
session_default_channel_group
This project is in BETA
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
The analytics data recorded provide a window into how people are interacting
with the government online. The data come from a unified Google Analytics
account for U.S. federal government agencies known as the Digital Analytics
Program (DAP). This program helps government agencies understand how people
find, access, and use government services online. The program does not track
individuals and anonymizes the IP addresses of visitors.
A subset of the DAP analytics data reports are available via the DAP API. These
reports may be limited to a specific domain or agency to support a wide range of
user needs. Report data are limited to sites which have a minimum of 50 visits
in the report period. Data may be subject to sampling and should not be relied
upon for 100% accuracy. This data should be used to examine high-level trends
and provide general insights into user demographics and behavior.
The URL for the API is
, and it
exposes 3 routes to query DAP analytics data:
/v
/v
/v
Quick Links:
Getting started
Authentication
Endpoints
Migrating from API V1 to API V2
Getting started
To begin using this API, you will need to register for an API Key. See the
Authentication
section for details.
Common use cases
Below are a few examples of API calls and their use cases. For the example calls
below we’ll use the
curl
library and a placeholder API key
1234
Find data for a date range
To limit a call to a certain time frame, use the
before
and
after
query
params
# Get 7 days of site data
curl --header "x-api-key: 1234" https://api.gsa.gov/analytics/dap/v2/reports/site/data?after=2024-06-01&before=2024-06-07
Find data for a particular domain name
To limit results to a certain domain, use the
/domain/my.domain.com
path
# Get top 10 downloads for ssa.gov
curl --header "x-api-key: 1234" https://api.gsa.gov/analytics/dap/v2/domain/www.ssa.gov/reports/download/data?limit=10
Find data for a particular agency
To limit results to a certain agency, use the
/agencies/some-agency
path
# Get traffic source data for the Department of State
curl --header "x-api-key: 1234" https://api.gsa.gov/analytics/dap/v2/agencies/state/reports/traffic-source/data
Authentication
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.
Loading signup form...
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.
Endpoints
There are 3 supported endpoints in the API. All endpoints are read-only, and
accessed with HTTP GET requests. All endpoints are preceded by an API version
Endpoint quick links:
API versions
/reports
/agencies
/domain
Query params
Response structure
HTTP response codes
OpenAPI specification file
API versions
DAP API V1 returns data from Google Analytics V3, also known as Universal
Analytics (UA). DAP API V1 data includes data recorded in UA by DAP from January
1st 2018 to Google’s retirement date for UA (June 24 2024).
Google has retired UA and new data may only be recorded in their new version,
Google Analytics V4 (GA4).
DAP API V2 returns data recorded in GA4 by DAP beginning on DAP’s launch
date for GA4 recording code, August 1st 2023 to the present.
The GA4 data returned has some slightly different fields which are described
in
Migrating from API V1 to API V2
Valid API versions are
1.1
and
. API version should be included in the path
for all endpoints like the following examples
# API V1
# API V2
/reports
This route returns data at a government wide scope. Report metrics will be
totals combining metrics for participating hostnames in all DAP agencies. See
available reports
for a list of all supported report
names. The
report_agency
field in the response data will be empty string or
undefined in these reports because they apply to all DAP agencies.
Path structure
Replace
with the API name of the desired report.
/reports/
Example
# Get 30 days of government wide user language demographics data
curl --header "x-api-key: 1234" https://api.gsa.gov/analytics/dap/v2/reports/language/data?after=2024-06-01&before=2024-06-30
/agencies
This route returns data at an agency scope. Report metrics will be totals
combining participating hostnames belonging to the requested agency. See
available agencies
for a list of agencies which
participate in the DAP program and their API agency name. See
available reports
for a list of all supported report
names.
Path structure
Replace
with the API name of the agency. Replace
with the API name of the desired report.
/agencies/
Example
# Get 30 days of user operating system demographics data for the Department of
# Defense
curl --header "x-api-key: 1234" https://api.gsa.gov/analytics/dap/v2/agencies/defense/reports/os/data?after=2024-06-01&before=2024-06-30
/domain
This route returns data at a domain scope. Report metrics will be totals
for the requested domain. The domain route supports only the
site
domain
, and
second-level-domain
report names.
Path structure
Replace
with the desired domain for the report. Replace
with the API name of the desired report.
/domain/
Example
# Get 30 days of visit data for www.ssa.gov
curl --header "x-api-key: 1234" https://api.gsa.gov/analytics/dap/v2/domain/www.ssa.gov/reports/site/data?after=2024-06-01&before=2024-06-30
Query params
The following query params are supported by all endpoints:
limit
: Limit the number of data points that are rendered. The default is
1000 and the max is 10,000
page
: Pages through the results. If the limit is set to
1000
, using
page=2
will render the 1001st through 2000th data point. Defaults to page 1.
after
: Limit the results to data with dates on or after the date specified.
Expects
YYYY-MM-DD
date format.
before
: Limit the results to data with dates on or before the date
specified. Expects
YYYY-MM-DD
date format. Defaults to the current date.
Response structure
All endpoints follow the same response structure. The response represents the
rows in the
data
array in the JSON reports that can be downloaded from
analytics.usa.gov, 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 point entry in the DAP API database.
report_name
: The name of the data point’s report
report_agency
: The name of the data point’s agency. This will be empty or
undefined when the data point is at the government wide scope
date
: The date/time corresponding to the data in the data point
visits
: 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. See
analytics definitions
for more details on dimensions and metrics.
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.
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
Available reports
The following reports can be queried using the API:
API report name
description
example /reports API call
The count of download events for each downloaded file
example
traffic-source
The count of visitors for each traffic source
example
device-model
The count of visitors for each device model
example
domain
The count of visitors for each domain
example
site
The count of visitors for each hostname
example
second-level-domain
The count of visitors to participating second-level-domains
example
language
The count of visitors for each browser language code
example
os-browser
The count of visitors broken down by browser and operating system
example
windows-browser
The count of visitors broken down by Windows versions and browser
example
browser
The count of visitors for each browser
example
windows-ie
The count of visitors broken down by Windows version and Internet Explorer versions (this report is only in API version 1.1)
example
os
The count of visitors for each operating system
example
windows
The count of visitors for each Windows version
example
ie
The count of users for each Internet Explorer version (this report is only in API version 1.1)
example
device
The count of users for each device type (desktop/mobile/tablet)
example
Available agencies
The following agencies can be queried using the API:
agency
API agency name
example /agencies API call
Agency for International Development
agency-international-development
example
American Battle Monuments Commission
american-battle-monuments-commission
example
Commodity Futures Trading Commission
commodity-futures-trading-commission
example
Consumer Financial Protection Bureau
consumer-financial-protection-bureau
example
Consumer Product Safety Commission
consumer-product-safety-commission
example
Corporation for National and Community Service
corporation-national-community-service
example
Defense Nuclear Facilities Safety Board
defense-nuclear-facilities-safety-board
example
Denali Commission
denali-commission
example
Department of Agriculture
agriculture
example
Department of Commerce
commerce
example
Department of Defense
defense
example
Department of Education
education
example
Department of Energy
energy
example
Department of Health and Human Services
health-human-services
example
Department of Homeland Security
homeland-security
example
Department of Housing and Urban Development
housing-urban-development
example
Department of the Interior
interior
example
Department of Justice
justice
example
Department of Labor
labor
example
Department of State
state
example
Department of Transportation
transportation
example
Department of the Treasury
treasury
example
Department of Veterans Affairs
veterans-affairs
example
Environmental Protection Agency
environmental-protection-agency
example
Equal Employment Opportunity Commission
equal-employment-opportunity-commission
example
Executive Office of the President
executive-office-president
example
Farm Credit Administration
farm-credit-administration
example
Federal Bureau of Investigation
federal-bureau-investigation
example
Federal Deposit Insurance Corporation
federal-deposit-insurance-corporation
example
Federal Election Commission
federal-election-commission
example
Federal Energy Regulatory Commission
federal-energy-regulatory-commission
example
Federal Housing Finance Agency
federal-housing-finance-agency
example
Federal Maritime Commission
federal-maritime-commission
example
Federal Mine Safety and Health Review Commission
federal-mine-safety-health-review-commission
example
Federal Retirement Thrift Investment Board
federal-retirement-thrift-investment-board
example
Federal Trade Commission
federal-trade-commission
example
General Services Administration
general-services-administration
example
Inter-American Foundation
inter-american-foundation
example
International Development Finance Corporation
international-development-finance-corporation
example
Merit Systems Protection Board
merit-systems-protection-board
example
Millennium Challenge Corporation
millennium-challenge-corporation
example
National Aeronautics and Space Administration
national-aeronautics-space-administration
example
National Archives and Records Administration
national-archives-records-administration
example
National Capital Planning Commission
national-capital-planning-commission
example
National Council on Disability
national-council-disability
example
National Credit Union Administration
national-credit-union-administration
example
National Education Association
national-education-association
example
National Endowment For The Humanities
national-endowment-humanities
example
National Labor Relations Board
national-labor-relations-board
example
National Mediation Board
national-mediation-board
example
National Oceanic and Atmospheric Administration
national-oceanic-atmospheric-administration
example
National Park Service
national-park-service
example
National Reconnaissance Office
national-reconnaissance-office
example
National Science Foundation
national-science-foundation
example
National Transportation Safety Board
national-transportation-safety-board
example
Nuclear Regulatory Commission
nuclear-regulatory-commission
example
Nuclear Waste Technical Review Board
nuclear-waste-technical-review-board
example
Office of the Director of National Intelligence
office-director-national-intelligence
example
Office of Government Ethics
office-government-ethics
example
Office of Navajo and Hopi Indian Relocation
office-navajo-hopi-indian-relocation
example
Office of Personnel Management
office-personnel-management
example
Peace Corps
peace-corps
example
Pension Benefit Guaranty Corporation
pension-benefit-guaranty-corporation
example
Postal Regulatory Commission
postal-regulatory-commission
example
Privacy and Civil Liberties Oversight Board
privacy-civil-liberties-oversight-board
example
Public Buildings Reform Board
public-buildings-reform-board
example
Securities and Exchange Commission
securities-exchange-commission
example
Small Business Adminstration
small-business-administration
example
Social Security Administration
social-security-administration
example
Special Inspector General for Afghanistan Reconstruction
special-inspector-general-afghanistan-restoration
example
Surface Transportation Board
surface-transportation-board
example
Tennessee Valley Authority
tennessee-valley-authority
example
Udall Foundation
udall-foundation
example
U.S. Access Board
access-board
example
U.S. Agency for Global Media
agency-global-media
example
U.S. Commission on Civil Rights
commission-civil-rights
example
U.S. Courts
us-courts
example
U.S. International Trade Commission
international-trade-commission
example
U.S. Postal Inspection Service
postal-inspection-service
example
U.S. Postal Service
postal-service
example
U.S. Railroad Retirement Board
railroad-retirement-board
example
U.S. Trade and Development Agency
trade-development-agency
example
Migrating from API V1 to API V2
Background
As described in
API versions
, API V1 returns data from Google
Analytics version 3, and DAP API V2 returns data from Google Analytics version
4.
The GA4 data returned has some slightly different fields which are described
below.
Requests
The DAP 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 DAP 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 from V1
browser_version
has_social_referral
exits
exit_page
New fields in V2
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’
To suggest a feature or ask for help, please
file an issue in our project repository