Bulk Filters API

Note: The Bulk Filters API is used for managing (creating, modifying, deleting) filters programmatically and is not enabled by default. Contact Conviva Support (support@conviva.com) to enable Bulk Filters API for your account. For basic data about filters, use the https://api.conviva.com/3.0/metrics/_meta/references/filters endpoint.
See Metrics V3 API User Guide for more details about programmatic access to the historical and real-time metrics.

Working with Bulk Filters

Bulk Filters API is a RESTful API and supports GET, POST, PUT and DELETE methods.

• The GET method retrieves existing filters, as well as filter dimensions as resource endpoints, where each endpoint supports various query parameters.

• The DELETE method identifies filters by their identifiers. Specify multiple identifiers for deletion at once.

• The POST or PUT methods ingest and return JSON formatted data. Use a JSON file to specify multiple filter settings.

For examples, see Use Case Scenarios.

Test Request

Use the API credentials to quickly test this API with a simple GET request. For example, view all the configured dimensions for filters:

GET http://api.conviva.com/bulk_filters/fields

The response is a JSON object with the dimension values available for the c3 account and a successful response status (HTTP code 200):

{
  "status": 200,
  "values": [
    "ASN",
    "Asset Name",
    "Browser Name",
    "Browser Version",
    "CDN",
    "City",
    "Client ID",
    "Continent",
    "Country",
    "Customer",
    "DMA",
    "Device Hardware Type",
    "Device Manufacturer",
    "Device Marketing Name",
    "Device Model",
    "Device Name",
    "Device Operating System",
    "Device Operating System Family",
    "Device Operating System Version",
    "ISP",
    "Content Category",
    "Player Framework Name",
    "Player Framework Version",
    "Player Name",
    "Postal Code",
    "Resource",
    "State",
    "Tag"
  ]
}

Status and Error Codes

Limitations

Each API call is capable to process a maximum of 100 filters.

Use Case Scenarios

Review some common use cases for GET, POST, PUT, and DELETE:

View Filters: GET

GET /bulk_filters?

Additional Lookup Endpoints

Use the pattern query paramter to search for values that contain a specific string value.

GET /bulk_filters/asn/?pattern=$SEARCH_STRING
GET /bulk_filters/categories/?pattern=$SEARCH_STRING
GET /bulk_filters/cities/?pattern=$SEARCH_STRING
GET /bulk_filters/continents/?pattern=$SEARCH_STRING
GET /bulk_filters/countries/?pattern=$SEARCH_STRING
GET /bulk_filters/dma/?pattern=$SEARCH_STRING
GET /bulk_filters/fields/?pattern=$SEARCH_STRING
GET /bulk_filters/isp/?pattern=$SEARCH_STRING
GET /bulk_filters/states/?pattern=$SEARCH_STRING
GET /bulk_filters/subcategories/?category=$CATEGORY_NAME&pattern=$SEARCH_STRING
GET /bulk_filters/tags/?pattern=$SEARCH_STRING

To extract the data from existing filters, use certain Experience Insights dimensions as resources/endpoints. Furthermore, using a combination of different parameters, depending on business cases, the queries become flexible and powerful. Conviva also provide certain paramenters to help limit and shape the API response.

All endpoints and possible parameters are listed in Bulk Filters API Reference.

Examples:

• To understand what filters are created by the admin1 user:
  GET /bulk_filters/?creator=admin1

• To target filters with specified IDs, in order to copy rules or properties:
  GET /bulk_filters/?id=1234,5678,101112

• To list all filters that are enabled for MetricLens/Diagnostics dashboards (i.e., advanced parameter set to true):
  GET /bulk_filters/?advanced=true

• To view filters with names that contain the string 'affiliate':
  GET /bulk_filters/?name=affiliate

• To view all filters in the Network category that are disabled GET /bulk_filters/?category=network&enabled=false

• To view all filters in the CDN subcategory:
  GET /bulk_filters/?subcategory=cdn

• To display account's configured dimensions, use the fields qualifier in the URL path:
  GET /bulk_filters/fields/

• To view all the ASN IDs configured for the account, use the ASN resource:
  GET /bulk_filters/asn/

• To view all city names configured in account's filters, use the cities resource:
  GET /bulk_filters/cities/

• To search for city names, use the cities resource with the pattern query parameter:
  GET /bulk_filters/cities/?pattern=foster+city

View Lookup Cities

View lookup cities with the string "united states".

Request

GET http://api.conviva.com/bulk_filters/cities/?pattern=united%20states

Response

{
  "status": 200,
  "values": [
    "'aiea, Hawaii, United States",
    "'o'okala, Hawaii, United States",
    "Aaronsburg, Pennsylvania, United States"
  ]
}

View Filters by Creation Date

View filters that were created on January 22, 2019 (use format YYYY-MM-DD).

Request

GET https://api.conviva.com/bulk_filters/?created=2019-01-22

Response

{
  "status": 200,
  "filters": [
    {
      "advanced": false,
      "category": "NETWORK",
      "content": false,
      "created": "2019-01-22T18:44:34+00:00",
      "creator": "admin",
      "edited": "2019-01-22T18:44:34+00:00",
      "editor": "admin",
      "enabled": true,
      "id": "116838",
      "name": "filters_management_api_100",
      "rules":
      {
        "op": "and",
        "rules": [
          {
            "op": "or",
            "rules": [{"field": "Customer","op": "contains","value": "c3.iOS"}]
          }
        ]
      },
      "subcategory": "Resource"
    }
  ]
}

View n-Number of Filters

View only 5 filters (limit=5) and restrict the results to just the filter ID and the creator name fields.

Request

GET https://api.conviva.com/bulk_filters/?fields=id,creator&limit=5

Response

[
  {
    "creator": "c3.company_admin",
    "id": 3387
  },
  {
    "creator": "c3.company_admin",
    "id": 3798
  },
  {
    "creator": "c3.company_admin",
    "id": 4013
  },
  {
    "creator": "test@company.com",
    "id": 27145
  },
  {
    "creator": "test@company.com",
    "id": 27151
  }
]

Create Filters: POST

Create many filters in bulk. For example, you have a new Service B, and wish to have the same standardised reporting capabilities as existing Service A. By replicating the rules for the existing Service A and making small changes in bulk, you can quickly spin up the reporting for Service B. An example workflow would be to use GET to copy Service A filters into a JSON file, use a text editor to change any fields in bulk, and inject this new JSON file using POST.

When editing the JSON file, please note that some fields under the "rules" arrays, such as ASN and country, have pre-set values. Other filter fields, such as asset name and client ID, are not limited to pre-set values and support either an existing value or any new value. Please review the reference guide for the pre-set limitiations and first use GET to view all the pre-set values for your filters.

POST /bulk_filters/

[
  {
    "name": "my new filter's name",
    "rules":
    {
      "op": "and",
      "rules": []
    }
  }
]

Create Multiple Filters

Create the filters using a JSON File, where @/admin/filter-file.json represents the path of a JSON file.

Request

POST https://api.conviva.com/bulk_filters/-d @/admin/filter-file.json"

Response

[
  {
    "name": "filter-one",
    "category": "CONTENT",
    "subcategory": "Asset",
    "advanced": true,
    "content": false,
    "enabled": false,
    "rules": {
      "op": "and",
      "rules": [
        {
          "op": "or",
          "rules": [
            {
              "field": "Asset Name",
              "op": "contains",
              "value": "aaa"
            },
            {
              "field": "Asset Name",
              "op": "contains",
              "value": "bbb"
            }
          ]
        },
        {
          "op": "or",
          "rules": [
            {
              "field": "Browser Name",
              "op": "not_contains",
              "value": "Chrome"
            },
            {
              "field": "Tag",
              "op": "not_contains",
              "value": "Chrome",
              "key": "customerBrowser"
            }
          ]
        }
      ]
    }
  },
  {
    "name": "filter-two",
    "category": "CONTENT",
    "subcategory": "Asset",
    "advanced": true,
    "content": false,
    "enabled": false,
    "rules": {
      "op": "and",
      "rules": [
        {
          "op": "or",
          "rules": [
            {
              "field": "Asset Name",
              "op": "contains",
              "value": "aaa"
            },
            {
              "field": "Asset Name",
              "op": "contains",
              "value": "bbb"
            }
          ]
        },
        {
          "op": "or",
          "rules": [
            {
              "field": "Browser Name",
              "op": "contains",
              "value": "Chrome"
            },
            {
              "field": "Tag",
              "op": "contains",
              "value": "Chrome",
              "key": "customerBrowser"
            }
          ]
        }
      ]
    }
  },
  {
    "name": "filter-three",
    "category": "CONTENT",
    "subcategory": "Asset",
    "advanced": true,
    "content": false,
    "enabled": true,
    "rules": {
      "op": "and",
      "rules": [
        {
          "op": "or",
          "rules": [
            {
              "field": "Asset Name",
              "op": "contains",
              "value": "aaa"
            },
            {
              "field": "Asset Name",
              "op": "contains",
              "value": "bbb"
            }
          ]
        },
        {
          "op": "or",
          "rules": [
            {
              "field": "Browser Name",
              "op": "not_contains",
              "value": "Chrome"
            },
            {
              "field": "Tag",
              "op": "not_contains",
              "value": "Chrome",
              "key": "customerBrowser"
            }
          ]
        }
      ]
    }
  }
]

Modify Filters: PUT

The key PUT scenarios include the ability to easily duplicate and modify pre-existing rules or do bulk edits of existing filters.

First, display a list of all existing filters using GET. Then based on the filter's ID, alter the rules or other filter fields. PUT will merge the new data with the existing data of the specified filter, selected by ID.

PUT expects a valid filter ID where the updates will be applied.

PUT /bulk_filters/

Rename Multiple Filters

Use a simple API call or a JSON file.

Request

PUT http://api.conviva.com/bulk_filters/ \  
  -d '[  
        { "id": 80510, "name": "new1" },  
        { "id": 80509, "name": "new2" }  
      ]'

Response

{  
  "location": "https://api.conviva.com/bulk_filters/?id=80509,80510",  
  "status": 200  
}

Modify Multiple Filters to Enable MetricLens Support

Request

PUT http://api.conviva.com/bulk_filters/ \  
      -d '[  
            {"id":80510,"advanced":true},  
            {"id":80509,"advanced":true}  
          ]'

Response

{
  "location": "https://api.conviva.com/bulk_filters/?id=80509,80510",
  "status": 200
}

Delete Filters: DELETE

Delete unwanted filters from services or campaigns that expired.

First, use the GET method to retrieve a list of filter IDs, then specify the IDs in the query parameter.

Required parameter: id (a list of comma-separated filter IDs).

Delete Multiple Filters by IDs

Request

DELETE https://api.conviva.com/bulk_filters/?id=117229,117300

Response

{
  "deleted": [
    {"id": 117299,"name": "117229"},
    {"id": 117300,"name": "117300"}
  ],
  "status": 200
}

Bulk Filters API Bulk Filters API Bulk Filters API