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.
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.
- This example shows all current day Published Reports: https://marsapi.ams.usda.gov//services/v1.1/public/listPublishedReports
- This example shows the most current date of all Published Reports ever released on MMN: https://marsapi.ams.usda.gov//services/v1.1/public/listPublishedReports/all
- This example shows the last Published Reports for the last 100 days. Users may change the day to any number: https://marsapi.ams.usda.gov//services/v1.1/public/listPublishedReports/100
- This example shows all Corrected Reports: https://marsapi.ams.usda.gov/services/v1.1/public/listCorrectedReports/all
- This example provides all Corrected Reports for the last 100 days. Users may change the day to any number: https://marsapi.ams.usda.gov/services/v1.1/public/listCorrectedReports/100