As "America's Data Agency," the Department of Commerce is prepared and well-positioned to foster the next phase in the open data revolution. But we cannot do it alone. We need your help. We invite you to use our content API to enhance the value, accessibility and usability of Commerce data for government, business and the public.
Below you will find the documentation for how to access and use our content API. For a prompt response to any question, request or idea for improvement related to this API, please submit an issue to our Github repository. Alternatively, you can email [email protected] and we'll get back to you within 5 working days.
Get Started
- An API key is required for access. Please sign up for a key below.
- API basics introduces you to the resources available in the API.
-
API details outlines all the operations offered by the API.
-
Field reference contains a comprehensive listing of all the API fields.
-
Query parameter reference contains a list of all available parameters that may be passed in the url.
-
Changelog lists the dates and changes to the API.
API key
API key is provided by api.data.gov. For full documentation on using your API key visit https://api.data.gov/docs/api-key/.
API basics
Commerce.gov content is exposed via a GET API available at https://api.commerce.gov/api/
Resources
| Endpoint | What it does |
|---|---|
| /api/blogs | Provides blog content entries and fields |
| /api/news | Provides newsroom content entries and fields |
| /api/image | Provides image content with fields |
The data results are stored in the data property of the JSON response, while the count, self, previous and next objects contain supporting information about the result set.
{
"data": [
{
"self": "https://api.commerce.gov/api/blogs/123",
"field": "A field value",
"field2": "Another field value"
},
// { ... more results follow ... }
],
"count": 100,
"self": {
"title": "Self",
"href": "https://api.commerce.gov/api/blogs?api_key=DEMO_KEY"
},
"previous": {
"title": "Previous",
"href": "https://api.commerce.gov/api/blogs?page=1&api_key=DEMO_KEY"
}
"next": {
"title": "Next",
"href": "https://api.commerce.gov/api/blogs?page=3&api_key=DEMO_KEY"
}
}
API Details
Returning documentation about the resource
Using an HTTP OPTIONS request, you can return machine structured documentation about a resource. To do so, send an OPTIONS request to the resource's root URL. The resource will respond with a JSON object that contains documentation for each field in the resource.
Browser: https://api.commerce.gov/api/blogs?api_key=DEMO_KEY
Returning specific fields
Using the ?fields query string, you can declare which fields should be returned. This is used, for example, if the resource has many fields, but your client only needs a few specific ones.
Browser: https://api.commerce.gov/api/blogs?fields=id,label,href&api_key=DEMO_KEY
Returns:
{
"data": [
{
"id": "2",
"label": "This is the title",
"href": "https://www.commerce.gov/news/blog/2015/08..."
}
]
}
Returning specific content
To return information for just one blog post append the ID to the end of the URL. To return multiple use a comma between IDs.
Browser: https://api.commerce.gov/api/blogs/1337,1492?api_key=DEMO_KEY
Applying a query filter
You may apply filters to the query used to generate the list of content. The default filter operator is equals (=) but this may be overridden and the following operators are available:
=, >, <, >=, <=, <>, !=, IN, BETWEEN, CONTAINS, LIKE, NOT IN and STARTS_WITH
Browser: https://api.commerce.gov/api/blogs?filter[label]=Manufacturing+Day+is+a+...
You can filter results using basic operators. For instance to get all the articles after a certain date:
Additionally you can provide multiple filters for the same field. That is specially useful when filtering on multiple value fields. The following example will get all the blog posts with the multi value field, categories, that contains BOTH 630 (Data) and 156 (Innovation).
Browser: https://api.commerce.gov/api/blogs?filter[categories][value][0]=630&filt...
Applying a query sort
You may apply a sort to the query used to generate the list of content.
Browser: https://api.commerce.gov/api/blogs?sort=label&api_key=DEMO_KEY
The sort order will default to ascending, however it can be set to descending by prepending a minus (-) sign the sort parameter value.
Browser: https://api.commerce.gov/api/blogs?sort=-label&api_key=DEMO_KEY
API versioning
The API is versionable so as it is changed and improve it will not break backward compatibility for existing consumers. You can request a specific version of the API by sending the X-API-Version HTTP header. Versions and changes are documented in the changelog.
Change request formatter
By default the API response is in simple json format but is also available in hal+json. In order to change the format send the Accept HTTP header.
Field reference
| Field name | Resource | Description | Type | Cardinality |
|---|---|---|---|---|
| id | all | Unique identifier for the entry | integer | 1 |
| label | all | Label, title or file name for the entry | string | 1 |
| self | all | Self-referencing URI to single entry in the API | uri | 1 |
| release_status | news | One of five options indicating how a press release or speech was released or indicating opinion editorial/fact sheet. FOR IMMEDIATE RELEASE (0), AS PREPARED FOR DELIVERY (1), AS DELIVERED (2), OPINION EDITORIAL (3), FACT SHEET(4). Note: When filtering by this field use key (in parenthesis) instead of value. | text | 1 |
| subtitle | news | Sub-title for the newsroom entry | text | 1 |
| href | all | Canonical URI for single entry (content page or full size image) on website | uri | 1 |
| post_date | blog, news | Official post date for the entry | date (unix time) | 1 |
| news_type | news | Classification of newsroom entry by type. Eg. "Press Releases", "Fact Sheets", "Secretary Speeches", "Deputy Secretary Speeches" and "Opinion Editorials". | taxonomy_term_reference | 1 |
| teaser | blog, news | Short snippet about the entry | text_long | 1 |
| publication | news | For Opinion Editorials only. Title and URL for original article published on external site. | uri | unlimited |
| body | blog, news | Main content body for the entry | text_long | 1 |
| image | blog, news | Image(s) associated with the entry | image | unlimited |
| video | blog, news | Video(s) associated with the entry | file | unlimited |
| galleries | blog, news | Galleries associated with the entry | entityreference | unlimited |
| documents | blog, news | Documents associated with the entry | taxonomy_term_reference | unlimited |
| categories | all | Categories associated with the entry | taxonomy_term_reference | unlimited |
| tags | all | Tags associated with the entry | taxonomy_term_reference | unlimited |
| admin_officials | all | Administrative Officials associated with the entry | taxonomy_term_reference | unlimited |
| orgs | all | Organizations and Groups associated with the entry | taxonomy_term_reference | unlimited |
| audience | blog, news | Audience targeted by the entry | taxonomy_term_reference | unlimited |
| related | blog, news | Other content related to the entry | entityreference | unlimited |
| created | all | Date the entry was created | date (unix time) | 1 |
| updated | all | Date the entry was last updated | date (unix time) | 1 |
| filesize | image | File size of image in bytes | integer | 1 |
| alt | image | Alternate text for the image | text | 1 |
| title | image | Title text for the image | text | 1 |
| caption | image | Caption associated with the image | text | 1 |
Query parameter reference
| Parameter | Required | What is does |
|---|---|---|
| range | No | Set's the limit for how many results you want back from a listing, per page. Maximum is 50, any range passed over 50 will still only result in 50 per page. |
| api_key | Yes (X-Api-Key header also an option) |
Allows you to access the API. Sign up now! |
| filter | No | Filter the API results by fields available in the API. Not all fields work as filters. |
| sort | No | Sort API results by fields available in the API. |
| page | No | Request specific page of results from the API. |
| fields | No | Only return fields specified. |
Changelog
- 9/23/2016 - Image v1.0: Initial release of API resource endpoint for Images/Photos. Added image specific fields to field reference and updated resource column.
- 12/5/2015 - News v1.0: Initial release of API resource endpoint for Newsroom content. Added newsroom specific fields to field reference and new column to show which fields are available for which content types.
- 10/07/2015 - Documentation updated for additional query filter operators.
- 10/05/2015 - Documentation updated to reflect query filter operator limitations and working example for simple filter on label field.
- 09/29/2015 - Blog v1.0: Initial release includes API resource endpoint for Blog content only.