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 firstname.lastname@example.org and we'll get back to you within 5 working days.
- 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 is provided by api.data.gov. For full documentation on using your API key visit https://api.data.gov/docs/api-key/.
Commerce.gov content is exposed via a GET API available at
|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 jsonapi, self, next, first, and prev objects contain supporting information about the result set.
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.
|type||all||API method name||string||1|
|id||all||Deprecated; Use uuid instead. Unique identifier for the entry||integer||1|
|nid or mid||all||Unique identifier for the entry. Image uses mid (media id)||integer||1|
|uuid||all||Unique identifier for the entry||uuid||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 three options indicating how a newsroom type - press release, report, speech, opinion editorial/fact sheet was released. FOR IMMEDIATE RELEASE, AS PREPARED FOR DELIVERY, AS DELIVERED.||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|
|post_date_formatted||blog, news||Official post date for the entry||date time(YYYY-MM-DDThh:mm:ss)||1|
|news_type||news||Classification of newsroom entry by type. Eg. "Press releases", "Reports", "Speeches", "Op-eds (Opinion editorials)" and "Fact sheets".||taxonomy_term_reference||1|
|teaser||blog, news||Deprecated. 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|
|speaker||news||For Speeches only. Speaker(s) associated with the entry||entityreference||unlimited|
|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||Deprecated. 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||Deprecated. 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|
|credit_line||image||Identifies the photographer, illustrator, or copyright holder for the image||text||1|
|copyright||image||Copyright info: USGW - U.S. government work; PDW - Public domain work; CCL - Creative Commons license; LSI - Licensed stock image; CW - Copyrighted work; INS - I'm not sure||text||1|
|image_perm_creator||image||Permission from image creator: WPO - Written permission obtained; INS - I'm not sure||text||1|
|image_perm_individual||image||Permission from individuals in photo: WPO - Written permission obtained; VPO - Verbal permission obtained; INS - I'm not sure||text||1|
- 11/9/2018 - News v2.0, Blogs v2.0, Image v2.0: Complete rewrite of the API to reflect the redesign of the Commerce.gov D8 website. API endpoints - news, blogs and image and their response fields preserved for backward compatibility. Advanced features such as returning specific fields, returning specific content, applying a query filter, applying a query sort, API versioning, and change request formatter are not available for this version. Fields with null values are returned as string with null value. Example "null".
- 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.