Metadata API Guide

The Metadata API is a set of read-only endpoints that return the valid values for building Metrics V3 and Sessions V3 requests. The endpoints return reference data for your c3 account, such as available dimensions, saved filters, geographic names, and KPI definitions. They do not return metric values.

Use these endpoints to look up:

• Dimension names, for the group-by path and the filter query parameter of a Metrics V3 request. See List dimensions.

• Saved filter IDs, for the filter_id query parameter. See List saved filters.

• City, state, country, and continent values, for the geographic dimensions. See Look up geography values.

• KPI IDs, for the kpi_id query parameter. See List KPIs.

Base URL and authentication

All endpoints use the HTTP GET method and the base URL https://api.conviva.com/insights/3.0. Paths in this guide are relative to that URL. Authenticate each request with the API client credentials for your c3 account. See Authentication for how to generate credentials and keep them out of the command line.

The examples in this guide use cURL with a netrc file, so no credentials appear in the command. Replace the placeholder values in braces, such as {filter_id}, with your own.

Endpoints

Reference endpoints

List reference endpoints

Returns the list of reference endpoints. Reference endpoints return non-metric metadata.

Method and path: GET /metrics/_meta/references

Parameters

None.

Response fields (HTTP 200)

Example request

curl --netrc "https://api.conviva.com/insights/3.0/metrics/_meta/references"

Example response

{
"references": [
{
"resource_name": "dimensions",
"endpoints": [
{
"methods": [
"GET"
],
"path": "https://api.conviva.com/insights/3.0/metrics/_meta/references/dimensions"
}
]
},
{
"resource_name": "cities",
"endpoints": [
{
"methods": [
"GET"
],
"path": "https://api.conviva.com/insights/3.0/metrics/_meta/references/cities"
},
{
"methods": [
"GET"
],
"path": "https://api.conviva.com/insights/3.0/metrics/_meta/references/cities/search"
}
]
}
]
}

List dimensions

Two endpoints return the dimensions available to your c3 account: one for Metrics V3 and one for Sessions V3.

Metrics V3 dimensions

Returns the dimensions available for grouping and filtering Metrics V3 data. Each entry gives the path to append to a metric request to group by the dimension, and the query parameter to filter by it. Dimensions defined for your account as custom tags are included and flagged.

Method and path: GET /metrics/_meta/references/dimensions

Parameters

None.

Response fields (HTTP 200)

To group by a dimension, append its group_by value to a metric request, for example /metrics/attempts/group-by/asset. To filter by it, add its query_filter parameter with a value, for example ?asset={asset_name}. For the Conviva-defined dimensions and their meanings, see Conviva-Defined Dimensions.

Example request

curl --netrc "https://api.conviva.com/insights/3.0/metrics/_meta/references/dimensions"

Example response

{
"dimensions": [
{
"name": "AS Numbers",
"group_by": "/asn",
"query_filter": "?asn",
"is_custom": false
},
{
"name": "Assets",
"group_by": "/asset",
"query_filter": "?asset",
"is_custom": false
},
{
"name": "Cities",
"group_by": "/geo-city-name",
"query_filter": "?geo_city_name",
"is_custom": false
},
{
"name": "My Example Tag",
"group_by": "/dimension-tag/myExampleTag",
"query_filter": "?tag_myExampleTag",
"is_custom": true
}
]
}

Sessions V3 dimensions

Returns the dimensions that Sessions V3 accepts as filters for your c3 account.

Method and path: GET /sessions/_meta/references/dimensions

Parameters

None.

Response fields (HTTP 200)

Example request

curl --netrc "https://api.conviva.com/insights/3.0/sessions/_meta/references/dimensions"

Example response

{
"dimensions": [
{
"name": "App Version",
"query_filter": "?app_version",
"is_custom": false
},
{
"name": "AS Numbers",
"query_filter": "?asn",
"is_custom": false
},
{
"name": "Assets",
"query_filter": "?asset",
"is_custom": false
}
]
}

List saved filters

The saved filters endpoints return the filters defined for your c3 account. Pass a filter id as the filter_id query parameter of a Metrics V3 or Sessions V3 request to apply the filter. To create, change, or delete saved filters, see the Bulk Filters API.

Metrics V3 saved filters

Returns the saved filters for your c3 account.

Method and path: GET /metrics/_meta/references/filters

Parameters

None.

Response fields (HTTP 200)

Example request

curl --netrc "https://api.conviva.com/insights/3.0/metrics/_meta/references/filters"

Example response

{
"filters": [
{
"id": "123456",
"name": "filter 1",
"category": "CONTENT/Asset",
"created_at": {
"epoch_ms": 1709649417000,
"iso_date": "2024-03-05T14:36:57.000Z"
}
},
{
"id": "234567",
"name": "filter 2",
"category": "CONTENT/Asset",
"created_at": {
"epoch_ms": 1709641048000,
"iso_date": "2024-03-05T12:17:28.000Z"
}
}
]
}

Sessions V3 saved filters

Returns the saved filters for your c3 account.

Method and path: GET /sessions/_meta/references/filters

Parameters

None.

Response fields (HTTP 200)

Example request

curl --netrc "https://api.conviva.com/insights/3.0/sessions/_meta/references/filters"

Example response

{
"filters": [
{
"id": "123456",
"name": "filter 1",
"category": "CONTENT/Asset",
"created_at": {
"epoch_ms": 1709649417000,
"iso_date": "2024-03-05T14:36:57.000Z"
}
},
{
"id": "234567",
"name": "filter 2",
"category": "CONTENT/Asset",
"created_at": {
"epoch_ms": 1709641048000,
"iso_date": "2024-03-05T12:17:28.000Z"
}
}
]
}

Look up geography values

The geography endpoints return the values that the geo-city-name, geo-state-name, geo-country-code, and geo-continent-name dimensions accept. The city and state lists are paginated, and each has a search endpoint. See Paging and search.

List cities

Returns a paginated list of the city names supported by the geo-city-name dimension.

Method and path: GET /metrics/_meta/references/cities

Parameters

Response fields (HTTP 200)

Example request

curl --netrc "https://api.conviva.com/insights/3.0/metrics/_meta/references/cities?page=1984&per_page=100"

Example response

{
"cities": [
"Nalzovice, Stredocesky Kraj, Czech Republic",
"Nalzovske Hory, Plzensky Kraj, Czech Republic",
"Nam Can, Tinh Ca Mau, Vietnam"
],
"_meta": {
"paging": {
"page": 1984,
"per_page": 100,
"total_count": 335838,
"total_pages": 3359
}
}
}

Search cities

Returns the city names that contain the search string.

Method and path: GET /metrics/_meta/references/cities/search

Parameters

Response fields (HTTP 200)

Example request

curl --netrc "https://api.conviva.com/insights/3.0/metrics/_meta/references/cities/search?q=foster%20city"

Example response

{
"cities": [
"Foster City, California, United States",
"Foster City, Michigan, United States"
],
"_meta": {
"queries": {
"q": "foster city"
}
}
}

List states

Returns a paginated list of the state names supported by the geo-state-name dimension.

Method and path: GET /metrics/_meta/references/states

Parameters

Response fields (HTTP 200)

Example request

curl --netrc "https://api.conviva.com/insights/3.0/metrics/_meta/references/states?page=12&per_page=100"

Example response

{
"states": [
"Central, Botswana",
"Central, Fiji",
"Central, Ghana"
],
"_meta": {
"paging": {
"page": 12,
"per_page": 100,
"total_count": 7541,
"total_pages": 76
}
}
}

Search states

Returns the state names that contain the search string.

Method and path: GET /metrics/_meta/references/states/search

Parameters

Response fields (HTTP 200)

Example request

curl --netrc "https://api.conviva.com/insights/3.0/metrics/_meta/references/states/search?q=california"

Example response

{
"states": [
"Baja California Sur, Mexico",
"Baja California, Mexico",
"California, United States"
],
"_meta": {
"queries": {
"q": "california"
}
}
}

List countries

Returns a look-up table that translates the country codes of the geo-country-code dimension to country names.

Method and path: GET /metrics/_meta/references/countries

Parameters

None.

Response fields (HTTP 200)

Example request

curl --netrc "https://api.conviva.com/insights/3.0/metrics/_meta/references/countries"

Example response

{
"code_to_name": {
"ad": [
"Andorra"
],
"ae": [
"United Arab Emirates"
],
"af": [
"Afghanistan"
],
"ax": [
"Aland Islands",
"åLand"
]
}
}

List continents

Returns the continent names supported by the geo-continent-name dimension.

Method and path: GET /metrics/_meta/references/continents

Parameters

None.

Response fields (HTTP 200)

Example request

curl --netrc "https://api.conviva.com/insights/3.0/metrics/_meta/references/continents"

Example response

{
"names": [
"Africa",
"Antarctica",
"Asia",
"Europe",
"North America",
"Oceania",
"South America"
]
}

List KPIs

KPIs

Returns the KPI IDs and names defined for your c3 account. Pass a kpi_id as the kpi_id query parameter of a Metrics V3 request to select the set of thresholds that calculates the metric. When the parameter is omitted, Metrics V3 uses kpi_id=1, Conviva Good. For more on KPIs, see the Metrics V3 API User Guide.

Method and path: GET /kpis

Parameters

None.

Response fields (HTTP 200)

Example request

curl --netrc "https://api.conviva.com/insights/3.0/kpis"

Example response

{
"kpis": [
{
"kpi_id": 1,
"kpi_name": "Conviva Good"
},
{
"kpi_id": 2,
"kpi_name": "Conviva Best"
}
]
}

Paging and search

The cities and states endpoints return one page of results per request. Set page and per_page to move through the list. Both parameters are integers with a minimum of 1. The response reports the position in the list in the _meta.paging object:

{
"_meta": {
"paging": {
"page": 12,
"per_page": 100,
"total_count": 7541,
"total_pages": 76
}
}
}

Request pages until page equals total_pages.

The search endpoints take the required q parameter, with a minimum of 3 characters, and return every name that contains the string, ignoring case. Search responses are not paginated. They echo the search string in _meta.queries.q.

Rate limits

The _meta endpoints share the rate limit with the Metrics V3 API: 30 QPM per c3 account (shared across all analytical queries). Requests that exceed the limit receive an HTTP 429 (Too Many Requests) response. Requests to the Sessions V3 endpoints count against the Sessions V3 limit in the same table. See Rate Limits in the Metrics V3 API User Guide for the current values.

For retry and caching guidance, see Efficient API Usage. Look-up data changes rarely, so cache the responses instead of requesting them before every query.

Related pages

• Metrics V3 API User Guide

• Sessions V3 API Guide

• Conviva-Defined Dimensions

• Bulk Filters API

• Authentication

• Efficient API Usage