Skip to content

Latest commit

 

History

History
205 lines (163 loc) · 11.9 KB

developer.md

File metadata and controls

205 lines (163 loc) · 11.9 KB
Raw
layout permalink
developer
/developer/

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 `v1.1`, please update your requests accordingly.
 </p>

The analytics.usa.gov API

In addition to being published and available for download, the data generated for this site is also available via an API.

Please note we have recently updated to v1.1, 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:

  • /reports/<report name>/data
  • /agencies/<agency name>/reports/<report name>/data
  • /domain/<domain>/reports/<report name>/data

API Keys

To use the API, please register for an API key below and include it in your query in this fashion:

  • https://api.gsa.gov/analytics/dap/v1.1/reports/download/data?api_key=DEMO_KEY1

{% raw %}

Loading signup form...
<script type="text/javascript"> /* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */ var apiUmbrellaSignupOptions = { // Pick a short, unique name to identify your site, like 'gsa-auctions' // in this example. registrationSource: 'gsa-dap-api', 
// Enter the API key you signed up for and specially configured for this
// API key signup embed form.
apiKey: 'LQekm6CxhGGrjRGkBsZjJD4R0Rr8sKYRtX1ey4qX',

// Provide an example URL you want to show to users after they signup.
// 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/download/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
// API URL are shown. HTML is allowed. Defaults to ""
// signupConfirmationMessage: '',

// OPTIONAL: Provide a URL to your own contact page to link to for user
// support. Defaults to "https://api.data.gov/contact/"
contactUrl: 'https://github.com/18F/analytics.usa.gov/issues',

// OPTIONAL: Set to true to verify the user's e-mail address by only
// sending them their API key via e-mail, and not displaying it on the
// signup confirmation web page. Defaults to false.
// verifyEmail: true,

// OPTIONAL: Set to false to disable sending a welcome e-mail to the
// user after signing up. Defaults to true.
// sendWelcomeEmail: false,

// OPTIONAL: Provide the name of your developer site. This will appear
// in the subject of the welcome e-mail as "Your {{siteName}} API key".
// Defaults to "api.data.gov".
// siteName: 'analytics.usa.gov',

// OPTIONAL: Provide a custom sender name for who the welcome email
// appears from. The actual address will be "noreply@api.data.gov", but
// this will change the name of the displayed sender in this fashion:
// "{{emailFromName}} <noreply@api.data.gov>". Defaults to "".
emailFromName: 'analytics.usa.gov',

// OPTIONAL: Provide an extra input field to ask for the user's website.
// Defaults to false.
// websiteInput: true,

// OPTIONAL: Provide an extra checkbox asking the user to agree to terms
// and conditions before signing up. Defaults to false.
// termsCheckbox: true,

// OPTIONAL: If the terms & conditions checkbox is enabled, link to this
// URL for your API's terms & conditions. Defaults to "".
// termsUrl: "https://agency.gov/api-terms/",

};

/* * * DON'T EDIT BELOW THIS LINE * * */ (function() { var apiUmbrella = document.createElement('script'); apiUmbrella.type = 'text/javascript'; apiUmbrella.async = true; apiUmbrella.src = 'https://api.data.gov/static/javascripts/signup_embed.js'; (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(apiUmbrella); })(); </script> Please enable JavaScript to signup for an api.data.gov API key.

{% endraw %}

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_time": "2017-04-07T14:00:00.000Z",
  "data": {
    "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
  • 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

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:

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:

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,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.
  • before: Limit the results to in dates on or before the date specified. Expects YYYY-MM-DD.