How to Use Singular API Filters

Use Singular API Filters to segment performance metrics by app, source, platform or country-level, or any custom dimension configured in Singular.

App and Source Filtered Query

To filter data on the app and/or source level, simply append the app and/or source parameters to your query and include the names of any relevant apps or sources.

For instance, append the following parameters to your query to return performance metrics for Fun-App1 and Fun-App2 on only the ad channels Facebook, Twitter and Pinterest.

&app=Fun-App1,Fun-App2&source=facebook,twitter,pinterest

Full query:

api.singular.net/api/v2.0/reporting?api_key={ENTER_YOUR_API_KEY}&app=Fun-App1,Fun-App2&source=facebook,twitter,pinterest

Filters Query

To drill deeper beyond app or source, use a Filters Query to return data filtered down to the platform or country-level, or other dimensions configured in Singular.

1. Retrieve available filters and their possible values.

api.singular.net/api/v2.0/reporting/filters?api_key={ENTER_YOUR_API_KEY}

Sample response here.

2. Construct a Filters Query

Using available dimensions and values returned from the /filters endpoint, you can construct your Filter Query against the /reporting endpoint.

Example Filters Query:

api.singular.net/api/v2.0/reporting?api_key={ENTER_YOUR_API_KEY}&filters=[{"dimension": "country", "operator": "in", "values":["rus,gbr,usa"]}, {"dimension": "os", "operator": "in", "values":["android"]}, {"dimension": "source", "operator": "in", "values":["facebook,twitter"]}

As you can see in the example query above, the filters parameter is a JSON list of filter objects each containing a dimension, values and an operator. Dimensions must be called using the dimension’s `name`, while values can be called by using either the `display_name` or `name`. Dimensions are case sensitive, while values are case insensitive.

Operator determines the filter type which can be `in` to include results matching the given values or `not in` to exclude results matching the given values.

For instance:

{“dimension”: “country”, “operator”: “not in”, “values”:[“usa”]}

This dimension would display results for all countries except results in the United States.

Check out our API documentation or contact Singular Support to learn more about Singular API Filters.

Join the Singular community & follow our journey at singular.net.

Please tap or click “♥︎” to help to promote this story to others.