Examples

Syntax :

None - as this is the default root URL of the API

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/reports/ -u api_key: 
JSON: https://marsapi.ams.usda.gov/services/v1.2/reports/

In the above example, the response data will be a Table of Contents of what is available on the API. Use the Slug ID to drill down to a specific report.

Sample of API Table of Contents

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Above is a sample of the Table of Contents pulled into Microsoft XLS. Use the Slug ID field to pull a specific report. 

Syntax :

<Slug ID>

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/reports/1234 -u api_key: 
JSON: https://marsapi.ams.usda.gov/services/v1.2/reports/1234

In the above example, the response data for 1234 (which is Green City Livestock Auction Replacement Cattle Special - Green City, MO) 

Syntax :

<Slug ID>?q=report_begin_date=mm/dd/yyyy&allSections=true

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/reports/1975?q=report_begin_date=05/29/2019&allSections=true -u api_key: 
JSON: https://marsapi.ams.usda.gov/services/v1.2/reports/1975?q=report_begin_date=05/29/2019&allSections=true

In the above example, the response data will give a full report of Slug ID 1975 for May 29, 2019 with all Sections of the report included.

Syntax :

<Slug ID>/<Section>?q=report_begin_date=mm/dd/yyyy

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/reports/1975/Volumes?q=report_begin_date=05/29/2019 -u api_key: 
JSON: https://marsapi.ams.usda.gov/services/v1.2/reports/1975/Volumes?q=report_begin_date=05/29/2019

In the above example, the response data will give partial report of Slug ID 1975 for May 29, 2019 only including the Volume Section of the report. 

Syntax :

<Slug ID>?q=commodity=<Value>;report_date=mm/dd/yyyy

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/reports/1280?q=commodity=Feeder%20Cattle;report_begin_date=06/03/2019 -u api_key: 
JSON: https://marsapi.ams.usda.gov/services/v1.2/reports/1280?q=commodity=Feeder Cattle;report_begin_date=06/03/2019

In the above example, the response data for 1280 (which is Oklahoma National Stockyards Market) will be filter by Commodity= Feeder Cattle and only show report date 04 JUN 2019. For the cURL example above, denote that when you have a space between word such as 'Feeder Cattle', you will need to place a %20 in between the words.

 
Syntax:

Commodity=<Value>, market_type=<Value>, holdings_current=<Value>,report_end_date=mm/dd/yyyy

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/reports/1095?q=commodity=Cheese;market_type=Cold%20Storage;holdings_current_lbs=94464576;report_end_date=01/15/2018 -u api_key:  
JSON: https://marsapi.ams.usda.gov/services/v1.2/reports/1095?q=commodity=Cheese;market_type=Cold Storage;holdings_current_lbs=94464576;report_end_date=01/15/2018

In the above example, the response data for the 1095 report will be filter by Commodity=cheese, market_type=Cold%20Storage, holdings_current_lbs, and by report_end_date, since there is no sort order available, the response will be sorted automatically by default sort order. 

Syntax :

commodity=<Value>;market_type=<Value>;report_end_date=mm/dd/yyyy:mm/dd/yyyy

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/reports/1095?q=commodity=Cheese;market_type=Cold%20Storage;report_end_date=01/15/2018:02/14/2018 -u api_key: 
JSON: https://marsapi.ams.usda.gov/services/v1.2/reports/1095?q=commodity=Cheese;market_type=Cold Storage;report_end_date=01/15/2018:02/14/2018

In the above example, the response data for the 1095 report will be filter by Commodity=cheese, market_type=Cold%20Storage and by report_end_date (between 2 dates). 

Syntax :

<SLUG ID>?q=commodity=Feeder Cattle

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/reports/1280?q=commodity=Feeder%20Cattle -u api_key: 
JSON: https://marsapi.ams.usda.gov/services/v1.2/reports/1280?q=commodity=Feeder Cattle

In the above example, the response data for report 1280 (which is Oklahoma National Stockyards Market) filtered on commodity of Feeder Cattle

Syntax :

<SLUG ID>?q=commodity=Feeder Cattle;report_begin_date=mm/dd/yyyy:mm/dd/yyyy

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/reports/1280?q=commodity=Feeder%20Cattle;report_begin_date=01/28/2019:02/01/2019 -u api_key: 
JSON: https://marsapi.ams.usda.gov/services/v1.2/reports/1280?q=commodity=Feeder Cattle;report_begin_date=01/28/2019:02/01/2019

In the above example, the response data for report 1280 (which is Oklahoma National Stockyards Market) filtered on commodity of only Feeder Cattle with a date range of 01 JAN 2019 to 01 FEB 2019. 

Syntax :

offices

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/offices -u api_key: 
JSON: https://marsapi.ams.usda.gov/services/v1.2/offices

In the above example, the response data will give a full list of Market News offices and the market commodity they collect 

Syntax :

marketTypes

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/marketTypes -u api_key: 
JSON: https://marsapi.ams.usda.gov/services/v1.2/marketTypes

In the above example, the response data will give a full list of Market Types and Market Type ID's.

Syntax :

commodities

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/commodities -u api_key: 
JSON: https://marsapi.ams.usda.gov/services/v1.2/commodities

In the above example, the response data will give a full list of commodities in MARS along with 'LOV ID's'.

Syntax :

offices/St Joseph

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/offices/St%20Joseph -u api_key: 
JSON: https://marsapi.ams.usda.gov/services/v1.2/offices/St Joseph

In the above example, the response data will give a full list of reports that are released by the St. Joseph, MO Market News Office. 

Syntax :

marketTypes/Auction Livestock

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/marketTypes/Auction%20Livestock -u api_key: 
JSON: https://marsapi.ams.usda.gov/services/v1.2/marketTypes/Auction Livestock

In the above example, the response data will give a full list of 'Auction Livestock' Market Type regardless of location. 

Syntax :

<Slug ID>/<Section>/<CorrectionsOnly>

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/reports/2194/Details?correctionsOnly=true -u api_key: 
JSON: https://marsapi.ams.usda.gov/services/v1.2/reports/2194/Details?correctionsOnly=true

In the above example, the response data will give correction details only in the last 3 business days for Slug ID 2194.

Syntax :

<Slug ID>/<Section>/<CorrectionsOnly=true&anyChanges Since=yyyy/mm/dd>

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/reports/2194/Details?CorrectionsOnly=true&anyChangesSince=2020/03/01 -u api_key: 
JSON: https://marsapi.ams.usda.gov/services/v1.2/reports/2194/Details?CorrectionsOnly=true&anyChangesSince=2020/03/01

In the above example, the response data will give correction details provided after 3/1/2020 for Slug ID 2194.

Syntax :

<Slug ID>/<Section>/<last Days>

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/reports/1089/Details?lastDays=50 -u api_key: 
JSON: https://marsapi.ams.usda.gov/services/v1.2/reports/1089/Details?lastDays=50

Updated Reports Index (v1.1)

The below are web-based API calls that can be made through a browser only. This is fixed text display output. There is no JSON file provided. These are examples and can be modified to use with other time frames.