API documentation

Retrieve targeting lists for a given URL

POST https://api.mediarithmics.com/v1/communities/:communityId/contextual/semantic_extraction

Path Parameters

Name	Type	Description
communityId*	integer	The ID of your community or organisation

Request Body

Name	Type	Description
url*	string	The URL for which you want to retrieve the list of attached targeting lists.
channel_id*	string	The ID of the channel associated with the URL.

200

{
    "status": "ok",
    "data": {
        "targeting_lists": [
            {
                "id": "123"
            },
            {
                "id": "456"
            }
        ]
    }
}

Retrieve all targeting lists

GET https://api.mediarithmics.com/v1/organisations/:organisationId/contextual/targeting_lists

Path Parameters

Name	Type	Description
organisationId*	integer	The ID of the organisation for which you want to retrieve the targeting lists

200

{
    "status": "ok",
    "data": [
        {
            "type": "SEMANTIC",
            "id": "1",
            "organisation_id": "1",
            "status": "INIT",
            "live_activation_ts": null,
            "name": "Targeting_List_Name",
            "short_description": "",
            "token": "cardinal-ack",
            "url_count": 21860,
            "last_30_days_page_views": 8066996,
            "created_ts": 1692607279222,
            "created_by": "1",
            "last_modified_ts": null,
            "last_modified_by": null,
            "archived": false,
            "query_id": "1"
        }
    ],
    "count": 1,
    "total": 1,
    "first_result": 0,
    "max_results": 10
}

Retrieve targeting list basic information

GET https://api.mediarithmics.com/v1/organisations/:organisationId/contextual/targeting_lists/:targetingListId

Path Parameters

Name	Type	Description
organisationId*	integer	The ID of the organisation
targetingListId*	Integer	The ID of the targeting list to retrieve

200

{
    "status": "ok",
    "data": {
        "type": "SEMANTIC",    // SEMANTIC, PANEL_BASED
        "id": "1",
        "organisation_id": "1",
        "segment_id": "7105867",    // Only for PANEL_BASED type
        "volume_ratio": 0.8313403,    // Only for PANEL_BASED type
        "status": "INIT",
        "live_activation_ts": null,
        "last_lift_computation_ts": 1700100423716,    // Only for PANEL_BASED type
        "name": "Targeting_List_Name",
        "short_description": "",
        "token": "cardinal-ack",
        "url_count": 21860,
        "last_30_days_page_views": 8066996,
        "created_ts": 1692607279222,
        "created_by": "1",
        "last_modified_ts": null,
        "last_modified_by": null,
        "archived": false,
        "query_id": "1"    // Only for SEMANTIC type
    }
}

Retrieve semantic targeting list query

GET https://api.mediarithmics.com/v1/organisations/:organisationId/contextual/queries/:queryId

Path Parameters

Name	Type	Description
organisationId*	integer	The ID of the organisation
queryId*	Integer	The ID of the query retrieved in a seamntic targeting list

200

{
    "status": "ok",
    "data": {
        "id": "1",
        "organisation_id": "1",
        "query_data": {
            "language_name": "JSON_SEMANTIC",
            "language_version": "1",
            "query": {
                "include": {
                    "entity_ids": [
                        "1",
                        "2"
                    ],
                    "iab_category_ids": [
                        "1"
                    ]
                },
                "exclude": {
                    "entity_ids": [],
                    "channel_ids": [
                        "1",
                        "2",
                        "3",
                        "4",
                        "5"
                    ],
                    "iab_category_ids": []
                }
            }
        },
        "created_by": "1",
        "created_ts": 1692607279084,
        "last_modified_by": null,
        "last_modified_ts": null
    }
}

Retrieve IAB category information

GET https://api.mediarithmics.com/v1/communities/:communityId/contextual/categories/:categoryId

Path Parameters

Name	Type	Description
communityId*	integer	The ID of the community
categoryId*	Integer	The ID of the category to be retrieved

200

{
    "status": "ok",
    "data": {
        "id": "25",
        "name": "News and Politics>Politics>War and Conflicts",
        "url_count": 13549,
        "last_30_days_page_views": 4914430
    }
}

Retrieve entity information

GET https://api.mediarithmics.com/v1/communities/:communityId/contextual/entities/:entityId

Path Parameters

Name	Type	Description
organisationId*	integer	The ID of the organisation
entityId*	Integer	The ID of the entity to be retrieved

200

{
    "status": "ok",
    "data": {
        "id": "287",
        "name": "Paris Saint-Germain Football Club",
        "type": "SoccerClub",
        "wikidata_id": "Q483020",
        "url_count": 4601,
        "last_30_days_page_views": 2095819
    }
}

Retrieve overal metrics for a particular query

POST https://api.mediarithmics.com/v1/communities/:communityId/contextual/analytics/overall_metrics

Path Parameters

Name	Type	Description
organisationId*	integer	The ID of the organisation

200

{
    "status":"ok",
    "data":
    {
        "url_count":13549,
        "last_30_days_page_views":4914430
    }
}

Retrieve panel based contextual targeting settings

GET https://api.mediarithmics.com/v1/audience_segments/:segmentId/contextual_targetings

Path Parameters

Name	Type	Description
segmentId*	integer	The ID of the audience segment on which

200

{
    "status": "ok",
    "data": [
        {
            "type": "PANEL_BASED",
            "id": "1",
            "organisation_id": "1",
            "segment_id": "1",
            "volume_ratio": 0.8313403,
            "status": "LIVE",
            "live_activation_ts": 1678193619193,
            "last_lift_computation_ts": 1700100423716,
            "name": "Targeting_List_Name",
            "short_description": null,
            "token": "double-beer-maryland",
            "url_count": 3746,
            "last_30_days_page_views": 63824027,
            "created_ts": 1678193048401,
            "created_by": "1",
            "last_modified_ts": 1700055578893,
            "last_modified_by": "1",
            "archived": false
        }
    ],
    "count": 1,
    "total": 1,
    "first_result": 0,
    "max_results": 2147483647
}

Publish a contextual targeting (LIVE)

POST https://api.mediarithmics.com/v1/audience_segments/:segmentId/contextual_targetings/:contextualTargetingId/actions

Path Parameters

Name	Type	Description
segmentId*	integer	The ID of the audience segment on which
contextualTargetingId*	Integer	The ID of the contextual targeting retrieved in creation response

Request Body

Name	Type	Description
type*	string	"PUBLISH"
volume_ratio*	float	% of audience segment reach (30-day page views) that will be used to calculate lift
activation_platforms*	array of strings	List of activation platforms where to activate the contexutal targeting. For instance ["XANDR"]

200

{
    "status":"ok",
    "data": {
        "id":"143",
        "segment_id":"128765",
        "volume_ratio":0.33580595,
        "status":"PUBLISHED",
        "activation_platforms":["XANDR"],
        "live_activation_ts":null,
        "last_lift_computation_ts":1676542526247,
        "created_ts":1676542452678,
        "created_by":"3594",
        "last_modified_ts":1676543040147,
        "last_modified_by": "3594",
        "archived":false
    }
}

Archive a contextual targeting

POST https://api.mediarithmics.com/v1/audience_segments/:segmentId/contextual_targetings/:contextualTargetingId/actions

Path Parameters

Name	Type	Description
segmentId*	integer	The ID of the audience segment on which
contextualTargetingId*	Integer	The ID of the contextual targeting retrieved in creation response

Request Body

Name	Type	Description
type*	string	"ARCHIVE"

200

{
    "status": "ok",
    "data": {
        "id": "143",
        "segment_id": "128765",
        "volume_ratio": 0.33580595,
        "status": "LIVE",
        "activation_platforms": [
            "XANDR"
        ],
        "live_activation_ts": 1676543074426,
        "last_lift_computation_ts": 1676542526247,
        "created_ts": 1676542452678,
        "created_by": "3594",
        "last_modified_ts": 1676548450358,
        "last_modified_by": "3594",
        "archived": true
    }
}