Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update DAP API docs #1134

Merged
merged 1 commit into from
Feb 28, 2024
Merged

Update DAP API docs #1134

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
179 changes: 111 additions & 68 deletions _apidocs/dap.md
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

approved.

Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,7 @@ title: analytics.usa.gov API
banner-heading: analytics.usa.gov API
---


<!-- Alpha status alert -->
<!-- Beta status alert -->
<div class="usa-alert usa-alert-warning" id="site-wide-alert" role="alert">
<div class="usa-alert-body">
<strong>
Expand All @@ -14,34 +13,30 @@ banner-heading: analytics.usa.gov API
This API is under active development, and breaking changes may be made without warning.
Have feedback or questions? <a href="https://github.com/18F/analytics.usa.gov/issues">Please let us know</a>!

Please note we have recently updated to `v1.1`, please update your requests accordingly.
Please note we have recently updated to `v2.0.0`, please update your requests accordingly.
</p>
</div>
</div>
<!-- end Alpha status alert -->

<!-- end Beta status alert -->

## 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 `v1.1`, please update your requests accordingly.**
**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/v1.1`, and it exposes 3 routes to query data:
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`


<p><small><a href="#">Back to top</a></small></p>

## 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.


{% raw %}
<div id="apidatagov_signup">Loading signup form...</div>
<script type="text/javascript">
Expand All @@ -59,7 +54,7 @@ To begin using this API, you will need to register for an API Key. You can sign
// This can be any API endpoint on your server, and you can use the
// special {{api_key}} variable to automatically substitute in the API
// key the user just signed up for.
exampleApiUrl: 'https://api.gsa.gov/analytics/dap/v1.1/reports/site/data?api_key={{api_key}}',
exampleApiUrl: 'https://api.gsa.gov/analytics/dap/v2.0.0/reports/site/data?api_key={{api_key}}',

// OPTIONAL: Provide extra content to display on the signup confirmation
// page. This will be displayed below the user's API key and the example
Expand Down Expand Up @@ -111,25 +106,21 @@ To begin using this API, you will need to register for an API Key. You can sign
})();
</script>
<noscript>Please enable JavaScript to signup for an <a href="http://api.data.gov/">api.data.gov</a> API key.</noscript>
{% endraw %}
{% endraw %}

| 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. |




<p><small><a href="#">Back to top</a></small></p>

## OpenAPI Specification File

You can view the full details of this API in the OpenAPI Specification file available here:
<a href="v1/openapi.yaml">Open API specification file for the Digital Analytics Program API</a>
<a href="v2/openapi.yaml">Open API specification file for the Digital Analytics Program API</a>

<p><small><a href="#">Back to top</a></small></p>


## 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:
Expand All @@ -139,10 +130,8 @@ The response represents the rows in the `data` array in the JSON reports that ca
"id": 60716,
"report_name": "today",
"report_agency": "justice",
"date_time": "2017-04-07T14:00:00.000Z",
"data": {
"visits": "4240"
},
"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"
}
Expand All @@ -153,64 +142,64 @@ Note that is has the following properties:
- `id`: The primary key of the data point
- `report_name`: The name of the data point's report
- `report_agency`: The name of the data point's agency
- `date_time`: The data/time the data in the data point corresponds to
- `data`: The data associated with the data point. This may contain child properties such as visits, browser, screen size, and so on, depending on the report
- `date`: The data/time the data in the data point corresponds to
- `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.

## 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](https://api.gsa.gov/analytics/dap/v1.1/reports/download/data?api_key=DEMO_KEY1))_
- traffic-source _([example](https://api.gsa.gov/analytics/dap/v1.1/reports/traffic-source/data?api_key=DEMO_KEY1))_
- device-model _([example](https://api.gsa.gov/analytics/dap/v1.1/reports/device-model/data?api_key=DEMO_KEY1))_
- domain _([example](https://api.gsa.gov/analytics/dap/v1.1/reports/domain/data?api_key=DEMO_KEY1))_
- site _([example](https://api.gsa.gov/analytics/dap/v1.1/reports/site/data?api_key=DEMO_KEY1))_
- second-level-domain _([example](https://api.gsa.gov/analytics/dap/v1.1/reports/second-level-domain/data?api_key=DEMO_KEY1))_
- language _([example](https://api.gsa.gov/analytics/dap/v1.1/reports/language/data?api_key=DEMO_KEY1))_
- os-browser _([example](https://api.gsa.gov/analytics/dap/v1.1/reports/os-browser/data?api_key=DEMO_KEY1))_
- windows-browser _([example](https://api.gsa.gov/analytics/dap/v1.1/reports/windows-browser/data?api_key=DEMO_KEY1))_
- browser _([example](https://api.gsa.gov/analytics/dap/v1.1/reports/browser/data?api_key=DEMO_KEY1))_
- windows-ie _([example](https://api.gsa.gov/analytics/dap/v1.1/reports/windows-ie/data?api_key=DEMO_KEY1))_
- os _([example](https://api.gsa.gov/analytics/dap/v1.1/reports/os/data?api_key=DEMO_KEY1))_
- windows _([example](https://api.gsa.gov/analytics/dap/v1.1/reports/windows/data?api_key=DEMO_KEY1))_
- ie _([example](https://api.gsa.gov/analytics/dap/v1.1/reports/ie/data?api_key=DEMO_KEY1))_
- device _([example](https://api.gsa.gov/analytics/dap/v1.1/reports/device/data?api_key=DEMO_KEY1))_
- download _([example](https://api.gsa.gov/analytics/dap/v2.0.0/reports/download/data?api_key=DEMO_KEY1))_
- traffic-source _([example](https://api.gsa.gov/analytics/dap/v2.0.0/reports/traffic-source/data?api_key=DEMO_KEY1))_
- device-model _([example](https://api.gsa.gov/analytics/dap/v2.0.0/reports/device-model/data?api_key=DEMO_KEY1))_
- domain _([example](https://api.gsa.gov/analytics/dap/v2.0.0/reports/domain/data?api_key=DEMO_KEY1))_
- site _([example](https://api.gsa.gov/analytics/dap/v2.0.0/reports/site/data?api_key=DEMO_KEY1))_
- second-level-domain _([example](https://api.gsa.gov/analytics/dap/v2.0.0/reports/second-level-domain/data?api_key=DEMO_KEY1))_
- language _([example](https://api.gsa.gov/analytics/dap/v2.0.0/reports/language/data?api_key=DEMO_KEY1))_
- os-browser _([example](https://api.gsa.gov/analytics/dap/v2.0.0/reports/os-browser/data?api_key=DEMO_KEY1))_
- windows-browser _([example](https://api.gsa.gov/analytics/dap/v2.0.0/reports/windows-browser/data?api_key=DEMO_KEY1))_
- browser _([example](https://api.gsa.gov/analytics/dap/v2.0.0/reports/browser/data?api_key=DEMO_KEY1))_
- windows-ie _([example](https://api.gsa.gov/analytics/dap/v2.0.0/reports/windows-ie/data?api_key=DEMO_KEY1))_
- os _([example](https://api.gsa.gov/analytics/dap/v2.0.0/reports/os/data?api_key=DEMO_KEY1))_
- windows _([example](https://api.gsa.gov/analytics/dap/v2.0.0/reports/windows/data?api_key=DEMO_KEY1))_
- ie _([example](https://api.gsa.gov/analytics/dap/v2.0.0/reports/ie/data?api_key=DEMO_KEY1))_
- device _([example](https://api.gsa.gov/analytics/dap/v2.0.0/reports/device/data?api_key=DEMO_KEY1))_

## 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](https://api.gsa.gov/analytics/dap/v1.1/agencies/agency-international-development/reports/site/data?api_key=DEMO_KEY1))_
- agriculture _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/agriculture/reports/site/data?api_key=DEMO_KEY1))_
- commerce _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/commerce/reports/site/data?api_key=DEMO_KEY1))_
- defense _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/defense/reports/site/data?api_key=DEMO_KEY1))_
- education _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/education/reports/site/data?api_key=DEMO_KEY1))_
- energy _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/energy/reports/site/data?api_key=DEMO_KEY1))_
- environmental-protection-agency _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/environmental-protection-agency/reports/site/data?api_key=DEMO_KEY1))_
- executive-office-president _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/executive-office-president/reports/site/data?api_key=DEMO_KEY1))_
- general-services-administration _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/general-services-administration/reports/site/data?api_key=DEMO_KEY1))_
- health-human-services _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/health-human-services/reports/site/data?api_key=DEMO_KEY1))_
- homeland-security _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/homeland-security/reports/site/data?api_key=DEMO_KEY1))_
- housing-urban-development _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/housing-urban-development/reports/site/data?api_key=DEMO_KEY1))_
- interior _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/interior/reports/site/data?api_key=DEMO_KEY1))_
- justice _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/justice/reports/site/data?api_key=DEMO_KEY1))_
- labor _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/labor/reports/site/data?api_key=DEMO_KEY1))_
- national-aeronautics-space-administration _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/national-aeronautics-space-administration/reports/site/data?api_key=DEMO_KEY1))_
- national-archives-records-administration _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/national-archives-records-administration/reports/site/data?api_key=DEMO_KEY1))_
- national-science-foundation _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/national-science-foundation/reports/site/data?api_key=DEMO_KEY1))_
- nuclear-regulatory-commission _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/nuclear-regulatory-commission/reports/site/data?api_key=DEMO_KEY1))_
- office-personnel-management _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/office-personnel-management/reports/site/data?api_key=DEMO_KEY1))_
- postal-service _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/postal-service/reports/site/data?api_key=DEMO_KEY1))_
- small-business-administration _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/small-business-administration/reports/site/data?api_key=DEMO_KEY1))_
- social-security-administration _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/social-security-administration/reports/site/data?api_key=DEMO_KEY1))_
- state _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/state/reports/site/data?api_key=DEMO_KEY1))_
- transportation _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/transportation/reports/site/data?api_key=DEMO_KEY1))_
- treasury _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/treasury/reports/site/data?api_key=DEMO_KEY1))_
- veterans-affairs _([example](https://api.gsa.gov/analytics/dap/v1.1/agencies/veterans-affairs/reports/site/data?api_key=DEMO_KEY1))_
- agency-international-development _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/agency-international-development/reports/site/data?api_key=DEMO_KEY1))_
- agriculture _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/agriculture/reports/site/data?api_key=DEMO_KEY1))_
- commerce _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/commerce/reports/site/data?api_key=DEMO_KEY1))_
- defense _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/defense/reports/site/data?api_key=DEMO_KEY1))_
- education _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/education/reports/site/data?api_key=DEMO_KEY1))_
- energy _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/energy/reports/site/data?api_key=DEMO_KEY1))_
- environmental-protection-agency _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/environmental-protection-agency/reports/site/data?api_key=DEMO_KEY1))_
- executive-office-president _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/executive-office-president/reports/site/data?api_key=DEMO_KEY1))_
- general-services-administration _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/general-services-administration/reports/site/data?api_key=DEMO_KEY1))_
- health-human-services _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/health-human-services/reports/site/data?api_key=DEMO_KEY1))_
- homeland-security _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/homeland-security/reports/site/data?api_key=DEMO_KEY1))_
- housing-urban-development _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/housing-urban-development/reports/site/data?api_key=DEMO_KEY1))_
- interior _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/interior/reports/site/data?api_key=DEMO_KEY1))_
- justice _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/justice/reports/site/data?api_key=DEMO_KEY1))_
- labor _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/labor/reports/site/data?api_key=DEMO_KEY1))_
- national-aeronautics-space-administration _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/national-aeronautics-space-administration/reports/site/data?api_key=DEMO_KEY1))_
- national-archives-records-administration _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/national-archives-records-administration/reports/site/data?api_key=DEMO_KEY1))_
- national-science-foundation _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/national-science-foundation/reports/site/data?api_key=DEMO_KEY1))_
- nuclear-regulatory-commission _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/nuclear-regulatory-commission/reports/site/data?api_key=DEMO_KEY1))_
- office-personnel-management _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/office-personnel-management/reports/site/data?api_key=DEMO_KEY1))_
- postal-service _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/postal-service/reports/site/data?api_key=DEMO_KEY1))_
- small-business-administration _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/small-business-administration/reports/site/data?api_key=DEMO_KEY1))_
- social-security-administration _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/social-security-administration/reports/site/data?api_key=DEMO_KEY1))_
- state _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/state/reports/site/data?api_key=DEMO_KEY1))_
- transportation _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/transportation/reports/site/data?api_key=DEMO_KEY1))_
- treasury _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/treasury/reports/site/data?api_key=DEMO_KEY1))_
- veterans-affairs _([example](https://api.gsa.gov/analytics/dap/v2.0.0/agencies/veterans-affairs/reports/site/data?api_key=DEMO_KEY1))_

## 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.
Expand All @@ -221,10 +210,9 @@ 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,000
- `page`: Pages through the results. If the limit is set to `1000`, using `page=2` will render the 1001st through 2000th data point.
- `after`: Limit the results to in dates on or after the date specified. Expects `YYYY-MM-DD`.
- `after`: Limit the results to in dates on or after the date specified. Expects `YYYY-MM-DD`.
- `before`: Limit the results to in dates on or before the date specified. Expects `YYYY-MM-DD`.


## HTTP Response Codes

The API will return one of the following responses:
Expand All @@ -238,9 +226,64 @@ The API will return one of the following responses:

<p><small><a href="#">Back to top</a></small></p>

## 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'

<p><small><a href="#">Back to top</a></small></p>

## Contact Us

To suggest a feature or ask for help, please [file an issue in our project repository](https://github.com/18F/analytics.usa.gov/issues).
To suggest a feature or ask for help, please [file an issue in our project repository](https://github.com/18F/analytics.usa.gov/issues).

<p><small><a href="#">Back to top</a></small></p>
Loading
Loading