diff --git a/_apidocs/dap.md b/_apidocs/dap.md index 3aa64c7c9..7a67af494 100644 --- a/_apidocs/dap.md +++ b/_apidocs/dap.md @@ -3,8 +3,7 @@ title: analytics.usa.gov API banner-heading: analytics.usa.gov API --- - - + - - + ## 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//data` - `/agencies//reports//data` - `/domain//reports//data` -

Back to top

## 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 %}
Loading signup form...
-{% 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. | - - -

Back to top

## 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 +Open API specification file for the Digital Analytics Program API

Back to top

- ## 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: @@ -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" } @@ -153,8 +142,8 @@ 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 @@ -162,21 +151,21 @@ Reports can be queried by substituting `` in the path with the name 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 @@ -184,33 +173,33 @@ Reports can be queried by substituting `` in the path with the name 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. @@ -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: @@ -238,9 +226,64 @@ The API will return one of the following responses:

Back to top

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

Back to top

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

Back to top

diff --git a/_apidocs/dap/v1/openapi.yaml b/_apidocs/dap/v1/openapi.yaml index 40adcb2ee..5099e1d9d 100644 --- a/_apidocs/dap/v1/openapi.yaml +++ b/_apidocs/dap/v1/openapi.yaml @@ -4,22 +4,100 @@ info: title: Analytics API description: 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. paths: - '/reports/{report_name}/data': + /reports/{report_name}/data: get: summary: Analytic Reports description: | - this endpoint returns analytic reports. + this endpoint returns analytic reports. + required: + - report_name parameters: - - name: report_name - in: path - description: Name of the report - required: true - schema: - type: string - - $ref: '#/components/parameters/limit' - - $ref: '#/components/parameters/page' - - $ref: '#/components/parameters/after' - - $ref: '#/components/parameters/before' + - name: report_name + in: path + description: Name of the report + required: true + schema: + type: string + - $ref: '#/components/parameters/limit' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/after' + - $ref: '#/components/parameters/before' + responses: + '200': + description: A JSON array of reports + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Reports' + default: + description: Unexpected error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /agencies/{agency_name}/reports/{report_name}/data: + get: + summary: Analytic Reports filtered by agency + description: this endpoint returns analytic reports that are filtered by agency. + parameters: + - name: report_name + in: path + description: Name of the report + required: true + schema: + type: string + format: string + - name: agency_name + in: path + description: Name of the agency + required: true + schema: + type: string + format: string + - $ref: '#/components/parameters/limit' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/after' + - $ref: '#/components/parameters/before' + responses: + '200': + description: A JSON array of reports + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Reports' + default: + description: Unexpected error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /domain/{domain}/reports/{report_name}/data: + get: + summary: Analytic Reports filtered by domain + description: this endpoint returns analytic reports that are filtered by domain. + parameters: + - name: report_name + in: path + description: Name of the report + required: true + schema: + type: string + format: string + - name: domain + in: path + description: Name of the domain + required: true + schema: + type: string + format: string + - $ref: '#/components/parameters/limit' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/after' + - $ref: '#/components/parameters/before' responses: '200': description: A JSON array of reports @@ -35,94 +113,17 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/agencies/{agency_name}/reports/{report_name}/data': - get: - summary: Analytic Reports filtered by agency - description: | - this endpoint returns analytic reports that are filtered by agency. - parameters: - - name: report_name - in: path - description: Name of the report - required: true - schema: - type: string - format: string - - - name: agency_name - in: path - description: Name of the agency - required: true - schema: - type: string - format: string - - $ref: '#/components/parameters/limit' - - $ref: '#/components/parameters/page' - - $ref: '#/components/parameters/after' - - $ref: '#/components/parameters/before' - responses: - '200': - description: A JSON array of reports - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Reports' - default: - description: Unexpected error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '/domain/{domain}/reports/{report_name}/data': - get: - summary: Analytic Reports filtered by domain - description: | - this endpoint returns analytic reports that are filtered by domain. - parameters: - - name: report_name - in: path - description: Name of the report - required: true - schema: - type: string - format: string - - - name: domain - in: path - description: Name of the domain - required: true - schema: - type: string - format: string - - $ref: '#/components/parameters/limit' - - $ref: '#/components/parameters/page' - - $ref: '#/components/parameters/after' - - $ref: '#/components/parameters/before' - responses: - '200': - description: A JSON array of reports - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Reports' - default: - description: Unexpected error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - - servers: - url: 'https://api.gsa.gov/analytics/dap/v1.1' components: schemas: Reports: type: object + required: + - id + - report_name + - report_agency + - date properties: id: type: integer @@ -131,16 +132,74 @@ components: type: string description: The name of the data point’s report. report_agency: - type: string - description: The name of the data point’s agency. - date_time: - type: string - description: The data/time the data in the data point corresponds to. - data: - type: string - description: 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 + type: string + description: The name of the data point’s agency. + date: + type: string + description: The date the data in the data point corresponds to. + # Fields below are optional and depend on the report requested + active_visitors: + type: integer + avg_session_duration: + type: number + browser: + type: string + browser_version: + type: string + city: + type: string + country: + type: string + device: + type: string + description: the type of device of the visitor. + domain: + type: string + event_label: + type: string + exit_page: + type: string + exits: + type: string + has_social_referral: + type: boolean + hour: + type: string + landing_page: + type: string + language: + type: string + mobile_device: + type: string + os: + type: string + description: the operating system of the visitor, i.e. Windows + os_version: + type: string + description: the operating system version of the visitor, i.e. Vista + page: + type: string + description: the path of the page visited + page_title: + type: string + pageviews: + type: integer + pageviews_per_session: + type: integer + screen_resolution: + type: string + source: + type: string + total_events: + type: integer + users: + type: integer + visits: + type: integer Error: type: object + required: + - message properties: message: type: string @@ -148,7 +207,6 @@ components: type: string example: type: string - parameters: limit: name: limit @@ -160,24 +218,24 @@ components: page: name: page in: query - description: Pages through the results. If the limit is set to 1000, using page=2 will render the 1001st through 2000th data point. + description: Pages through the results. If the limit is set to 1000, using page=2 will render the 1001st through 2000th data point. schema: type: integer required: false after: name: after in: query - description: Limit the results to in dates on or after the date specified. Expects YYYY-MM-DD. + description: Limit the results to in dates on or after the date specified. Expects YYYY-MM-DD. schema: type: integer - required: false + required: false before: name: before in: query - description: Limit the results to in dates on or before the date specified. Expects YYYY-MM-DD. + description: Limit the results to in dates on or before the date specified. Expects YYYY-MM-DD. schema: type: integer - required: false + required: false securitySchemes: ApiKeyAuth: # arbitrary name for the security scheme type: apiKey diff --git a/_apidocs/dap/v2/openapi.yaml b/_apidocs/dap/v2/openapi.yaml new file mode 100644 index 000000000..c8ba7e9d1 --- /dev/null +++ b/_apidocs/dap/v2/openapi.yaml @@ -0,0 +1,245 @@ +openapi: 3.0.0 +info: + version: 2.0.0 + title: Analytics API + description: 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. +paths: + /reports/{report_name}/data: + get: + summary: Analytic Reports + description: | + this endpoint returns analytic reports. + required: + - report_name + parameters: + - name: report_name + in: path + description: Name of the report + required: true + schema: + type: string + - $ref: '#/components/parameters/limit' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/after' + - $ref: '#/components/parameters/before' + responses: + '200': + description: A JSON array of reports + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Reports' + default: + description: Unexpected error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /agencies/{agency_name}/reports/{report_name}/data: + get: + summary: Analytic Reports filtered by agency + description: this endpoint returns analytic reports that are filtered by agency. + parameters: + - name: report_name + in: path + description: Name of the report + required: true + schema: + type: string + format: string + - name: agency_name + in: path + description: Name of the agency + required: true + schema: + type: string + format: string + - $ref: '#/components/parameters/limit' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/after' + - $ref: '#/components/parameters/before' + responses: + '200': + description: A JSON array of reports + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Reports' + default: + description: Unexpected error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /domain/{domain}/reports/{report_name}/data: + get: + summary: Analytic Reports filtered by domain + description: this endpoint returns analytic reports that are filtered by domain. + parameters: + - name: report_name + in: path + description: Name of the report + required: true + schema: + type: string + format: string + - name: domain + in: path + description: Name of the domain + required: true + schema: + type: string + format: string + - $ref: '#/components/parameters/limit' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/after' + - $ref: '#/components/parameters/before' + responses: + '200': + description: A JSON array of reports + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Reports' + default: + description: Unexpected error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' +servers: + - url: 'https://api.gsa.gov/analytics/dap/v2' +components: + schemas: + Reports: + type: object + required: + - id + - report_name + - report_agency + - date + properties: + id: + type: integer + description: Generated unique identifier. + report_name: + type: string + description: The name of the data point’s report. + report_agency: + type: string + description: The name of the data point’s agency. + date: + type: string + description: The date the data in the data point corresponds to. + # Fields below are optional and depend on the report requested + active_visitors: + type: integer + avg_session_duration: + type: number + bounce_rate: + type: number + browser: + type: string + city: + type: string + country: + type: string + device: + type: string + description: the type of device of the visitor. + domain: + type: string + event_label: + type: string + file_name: + type: string + hour: + type: string + landing_page: + type: string + language: + type: string + language_code: + type: string + mobile_device: + type: string + os: + type: string + description: the operating system of the visitor, i.e. Windows + os_version: + type: string + description: the operating system version of the visitor, i.e. Vista + page: + type: string + description: the path of the page visited + page_title: + type: string + pageviews: + type: integer + pageviews_per_session: + type: integer + screen_resolution: + type: string + session_default_channel_group: + type: string + source: + type: string + total_events: + type: integer + users: + type: integer + visits: + type: integer + Error: + type: object + required: + - message + properties: + message: + type: string + required_fields: + type: string + example: + type: string + parameters: + limit: + name: limit + in: query + description: Limit the number of data points that are rendered. The default is 1000 and the max is 10,000 + schema: + type: integer + required: false + page: + name: page + in: query + description: Pages through the results. If the limit is set to 1000, using page=2 will render the 1001st through 2000th data point. + schema: + type: integer + required: false + after: + name: after + in: query + description: Limit the results to in dates on or after the date specified. Expects YYYY-MM-DD. + schema: + type: integer + required: false + before: + name: before + in: query + description: Limit the results to in dates on or before the date specified. Expects YYYY-MM-DD. + schema: + type: integer + required: false + securitySchemes: + ApiKeyAuth: # arbitrary name for the security scheme + type: apiKey + in: header # can be "header", "query" or "cookie" + name: X-API-KEY # name of the header, query parameter or cookie +security: + - ApiKeyAuth: []