Filtering is how to query the data for a specific response. Filtering can be implemented as a query parameter named for the field to be filtered on. The query response is based on a condition(s) the user provides. For example, the user wants to filter cheese data from the large data set.

The MARS APIs provides several ways to filter or query the response. 

Single Filter:

Syntax :

q=<<field_name>>=<<value>>

Keyword q informs the API that the user is requesting the response to be filtered. When filtering by the response fields, we should be careful to only pick the fields that are available in the response. 

Syntax :

q=commodity=Cheese

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/reports/1095?q=commodity=Cheese -u api_key:
JSON: https://marsapi.ams.usda.gov/services/v1.2/reports/1095?q=commodity=Cheese

In the example above the response is filtered by commodity=Cheese. 
 

Multiple Filters:

To enable filtering by multiple values, the fields should be separated with "," as the value separator.

Syntax :

q=<<field_name>>=<<value1>>,<<value2>>

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/reports/1095?q=commodity=Cheese,Butter -u api_key:
JSON: https://marsapi.ams.usda.gov/services/v1.2/reports/1095?q=commodity=Cheese,Butter

In the above example, the report 1095 is filtered by commodity in (Cheese, Butter).

To enable filtering of a field name using the between range, the values should be separated with ":" .

Syntax :

q=<<field_name>>=<<value1>>:<<value2>>

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/reports/1095?q=report_begin_date=2017-06-05:2017-07-01 -u api_key:
JSON: https://marsapi.ams.usda.gov/services/v1.2/reports/1095?q=report_begin_date=2017-06-05:2017-07-01

In the above example, the report 1095 is filtered by report_begin_date between '2017-06-05' and '2017-07-01'.

To enable filtering by multiple field name, the field should be separated with ";" as the condition separator.

Syntax :

q=<<field_name1>>=<<value1>>;<<field_name2>>=<<value2>>

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/reports/1095?q=commodity=Cheese;holdings_unit=LBS -u api_key:
JSON: https://marsapi.ams.usda.gov/services/v1.2/reports/1095?q=commodity=Cheese;holdings_unit=LBS

In the above example, the report 1095 is filtered by Commodity=cheese and by holdings_unit = LBS.

To enable filtering by multiple field name, and sorting using a different field use the below example.

Syntax :

q=<<field_name1>>=<<value1>>;<<field_name2>>=<<value2>>&sort=<<field_name3>>

Example :

cURL: curl https://marsapi.ams.usda.gov/services/v1.2/reports/1095?q=commodity=Cheese;holdings_unit=LBS&sort=quality -u api_key:
JSON: https://marsapi.ams.usda.gov/services/v1.2/reports/1095?q=commodity=Cheese;holdings_unit=LBS&sort=quality

In the above example, the report 1095 is filtered by Commodity=cheese and then by holdings_unit = LBS.