What is an API? 

An API is a tool that allows data to be retrieved from one system by another system or application.  The data can then be used in other websites, applications, compiled into reports, for your own data analysis, and more.  APIs are all about connection and information sharing - integrating data from one source to another.  APIs were created to satisfy a demand for access to data. The more APIs that are developed, the more the appetite for API consumption has grown.  APIs enable website, web, and mobile software to build applications that were not possible before APIs. 

Can I search data in the API by commodity? 

Currently, you are only able to retrieve data based on the report number, not the commodity.  For instance, if you wanted to retrieve all feeder cattle reports, you would to tell your software to pull reports that have feeder cattle, not just feeder cattle data. In the future we anticipate to expand this searching functionality. 

When will all USDA Market News data be available on the API?

USDA Market News data will continue to be moved into the new system over the next 2 to 3 years.  We are currently bringing data online one commodity at a time.  If you have questions on which commodities are currently available, please contact us at mars@ams.usda.gov.

Is the API the only way to see USDA Market News data? 

The API is not the only way.  You can use our traditional market reports like you always have or you can use the quick search on the My Market News home page. 

Do I have to register to use the MARS API? 

It is preferred that you register to use the MARS API.  With registration, MARS API provides each logged-in user their unique API key which allows you to take full advantage of My Market News' capabilities and provides a layer of security for both your system and ours.  Additionally, by registering, USDA Market News is able to monitor what data is being pulled, therefore allowing us to provide better services. Currently there is a sample key you can use without registering but it will be removed sometime in the future. 

Unregistered users are limited to pulling 5000 rows of data per request. Registered users can pull 100,000 at a time. 

What is the MARS API URL?

To communicate with the MARS API, your software needs a URL to tell it where to go, or an endpoint.  The API endpoint is https://marsapi.ams.usda.gov/services/v1.2/reports.

Can you search the data by commodity?

Reports by Commodity is one of the choices offered on the MyMarketNews homepage.  When accessing report data via MyMarketNews or the MARS API, you are also able to filter by commodity.  However, you cannot search a single commodity across reports at this time.

I’ve already been on the API and had some issues filtering and sorting by published date.  Why is this happening?

As new commodities are added to MARS over the next year, they will also begin appearing in MyMarketNews and the MARS API.  This time of development will naturally be accompanied by some issues and inconveniences.  Please feel free to contact us at mars@ams.usda.gov at any time with any questions or concerns.  We are constantly working to improve this new architecture.

Does AMS limit the number of queries a user can have in a given time frame?

No.  It is true that the number of rows is limited in the call back, but a registered user can pull back a much larger number of rows at one time than an unregistered user can.  Once you have registered with eAuthentication, you will have the ability to pull larger data sets..

Does the MARS API support webhooks?

This functionality is not currently included with this API. 

Don't see your question? Email the team at mars@ams.usda.gov.