# API documentation

## Retrieve targeting lists for a given URL

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/communities/:communityId/contextual/semantic_extraction`

#### Path Parameters

| Name                                          | Type    | Description                              |
| --------------------------------------------- | ------- | ---------------------------------------- |
| communityId<mark style="color:red;">\*</mark> | integer | The ID of your community or organisation |

#### Request Body

| Name                                          | Type   | Description                                                                  |
| --------------------------------------------- | ------ | ---------------------------------------------------------------------------- |
| url<mark style="color:red;">\*</mark>         | string | The URL for which you want to retrieve the list of attached targeting lists. |
| channel\_id<mark style="color:red;">\*</mark> | string | The ID of the channel associated with the URL.                               |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

## Retrieve all targeting lists

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/organisations/:organisationId/contextual/targeting_lists`

#### Path Parameters

| Name                                             | Type    | Description                                                                   |
| ------------------------------------------------ | ------- | ----------------------------------------------------------------------------- |
| organisationId<mark style="color:red;">\*</mark> | integer | The ID of the organisation for which you want to retrieve the targeting lists |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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
}
```

{% endtab %}
{% endtabs %}

## Retrieve targeting list basic information

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/organisations/:organisationId/contextual/targeting_lists/:targetingListId`

#### Path Parameters

| Name                                              | Type    | Description                              |
| ------------------------------------------------- | ------- | ---------------------------------------- |
| organisationId<mark style="color:red;">\*</mark>  | integer | The ID of the organisation               |
| targetingListId<mark style="color:red;">\*</mark> | Integer | The ID of the targeting list to retrieve |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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
    }
}
```

{% endtab %}
{% endtabs %}

## Retrieve semantic targeting list query

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/organisations/:organisationId/contextual/queries/:queryId`

#### Path Parameters

| Name                                             | Type    | Description                                                |
| ------------------------------------------------ | ------- | ---------------------------------------------------------- |
| organisationId<mark style="color:red;">\*</mark> | integer | The ID of the organisation                                 |
| queryId<mark style="color:red;">\*</mark>        | Integer | The ID of the query retrieved in a seamntic targeting list |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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
    }
}
```

{% endtab %}
{% endtabs %}

## Retrieve IAB category information&#x20;

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/communities/:communityId/contextual/categories/:categoryId`

#### Path Parameters

| Name                                          | Type    | Description                            |
| --------------------------------------------- | ------- | -------------------------------------- |
| communityId<mark style="color:red;">\*</mark> | integer | The ID of the community                |
| categoryId<mark style="color:red;">\*</mark>  | Integer | The ID of the category to be retrieved |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

## Retrieve entity information&#x20;

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/communities/:communityId/contextual/entities/:entityId`

#### Path Parameters

| Name                                             | Type    | Description                          |
| ------------------------------------------------ | ------- | ------------------------------------ |
| organisationId<mark style="color:red;">\*</mark> | integer | The ID of the organisation           |
| entityId<mark style="color:red;">\*</mark>       | Integer | The ID of the entity to be retrieved |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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
    }
}
```

{% endtab %}
{% endtabs %}

## Retrieve overal metrics for a particular query

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/communities/:communityId/contextual/analytics/overall_metrics`

#### Path Parameters

| Name                                             | Type    | Description                |
| ------------------------------------------------ | ------- | -------------------------- |
| organisationId<mark style="color:red;">\*</mark> | integer | The ID of the organisation |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

## Retrieve panel based contextual targeting settings

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/audience_segments/:segmentId/contextual_targetings`

#### Path Parameters

| Name                                        | Type    | Description                             |
| ------------------------------------------- | ------- | --------------------------------------- |
| segmentId<mark style="color:red;">\*</mark> | integer | The ID of the audience segment on which |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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
}
```

{% endtab %}
{% endtabs %}

## Publish a contextual targeting (LIVE)&#x20;

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/audience_segments/:segmentId/contextual_targetings/:contextualTargetingId/actions`

#### Path Parameters

| Name                                                    | Type    | Description                                                       |
| ------------------------------------------------------- | ------- | ----------------------------------------------------------------- |
| segmentId<mark style="color:red;">\*</mark>             | integer | The ID of the audience segment on which                           |
| contextualTargetingId<mark style="color:red;">\*</mark> | Integer | The ID of the contextual targeting retrieved in creation response |

#### Request Body

| Name                                                    | Type             | Description                                                                                      |
| ------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------ |
| type<mark style="color:red;">\*</mark>                  | string           | "PUBLISH"                                                                                        |
| volume\_ratio<mark style="color:red;">\*</mark>         | float            | % of audience segment reach (30-day page views) that will be used to calculate lift              |
| activation\_platforms<mark style="color:red;">\*</mark> | array of strings | List of activation platforms where to activate the contexutal targeting. For instance \["XANDR"] |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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
    }
}
```

{% endtab %}
{% endtabs %}

## Archive a contextual targeting

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/audience_segments/:segmentId/contextual_targetings/:contextualTargetingId/actions`

#### Path Parameters

| Name                                                    | Type    | Description                                                       |
| ------------------------------------------------------- | ------- | ----------------------------------------------------------------- |
| segmentId<mark style="color:red;">\*</mark>             | integer | The ID of the audience segment on which                           |
| contextualTargetingId<mark style="color:red;">\*</mark> | Integer | The ID of the contextual targeting retrieved in creation response |

#### Request Body

| Name                                   | Type   | Description |
| -------------------------------------- | ------ | ----------- |
| type<mark style="color:red;">\*</mark> | string | "ARCHIVE"   |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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
    }
}
```

{% endtab %}
{% endtabs %}