Producing APIs through Data.gov

One way agencies can offer APIs for their data is to use the built–in functionality of Data.gov. The information that is hosted as interactive datasets have an API layer which agencies can make available through documentation in the developer’s section of the agency’s website. The guide below will help you do this.

Process

1. Upload a dataset as an interactive dataset in Data.gov. A. Your agency should have a Data.gov point–of–contact who can help. If you need help finding yours, contact the Data.gov team.
2. Once the dataset is live in Data.gov’s interactive datasets catalog, click on ‘Export’ (in the top right), then ‘API’. You’ll need the resulting information in a moment.
3. Create an html page within your agency’s developer hub that will serve as an API homepage for this documentation (e.g., www.agency.gov/developer/name-of-api).
4. Customize the template below with the appropriate API information from your interactive dataset (see #2) and add the information to the API homepage that you’ve created. A. For the API URL, copy the ‘API Access Endpoint’, remove the ‘json’ suffix, and insert ‘[format]’.B. The ‘Response Format’, ‘Type’, and ‘Authentication’ fields do not need customizing.C. For the ‘Example Requests’, begin with the dataset’s ‘API Access Endpoint’, and customize it with parameters and values that demonstrate potential uses of this dataset’s API.D. For the Parameter’s Chart, describe each of the parameters listed in the ‘Column IDs’ and provide examples that are used in the dataset. It may be appropriate to combine some Column IDs, for instance, along the lines of the example below.
5. Include a link to the ‘Further Developer Documentation‘ that Socrata offers.
6. Link to any additional developer resources you create to a ‘Related Resources’ section.

Template

Name of Dataset

This section is a description of the dataset and some background for the API. Use plain language to describe what the underlying data is and what developers can do with it. Avoid insider language and acronyms—remember to ask whether someone who is new to your agency’s work would easily understand it.

API URL

http://explore.data.gov/resource/_[dataset-id]_.

[format]

Response Format

json, xml

Type

HTTP GET

Authentication

None required

Example Request

[See the example for a model to use]

Parameters and Values

<td>
  <strong>Type</strong>
</td>

<td>
  <strong>Description</strong>
</td>

<td>
  <strong>Sample Values</strong>
</td>

<td>
  <strong> </strong>
</td>

<td>
  <strong> </strong>
</td>

<td>
  <strong> </strong>
</td>

<td>
</td>

<td>
</td>

<td>
</td>

<td>
</td>

<td>
</td>

<td>
</td>

[See the example for a model to use]

Further Developer Documentation

Socrata’s SODA Documentation

Related Resources

Include any additional resources your team can offer developers.

Completed Example

To see this model in action, check out GSA’s Per Diem API.