API documentation for Commerce.gov

Tools and Resources
Post a comment

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 api@doc.gov 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/.

Loading signup form...

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.


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:


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:

Browser: https://api.commerce.gov/api/blogs?filter[created][value]=1426766400&filter[created][operator]=">="&api_key=DEMO_KEY

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.

Related content

Last updated: 2016-09-23 13:36

Bureaus & Offices

Search by organization name or browse the tree below