Get Contextual Segments
curl --request POST \
--url https://api.permutive.com/ctx/v1/segment \
--header 'Content-Type: application/json' \
--data '
{
"url": "<string>",
"page_properties": {
"client": {
"url": "<string>",
"domain": "<string>",
"referrer": "<string>",
"type": "<string>",
"user_agent": "<string>",
"title": "<string>"
}
}
}
'import requests
url = "https://api.permutive.com/ctx/v1/segment"
payload = {
"url": "<string>",
"page_properties": { "client": {
"url": "<string>",
"domain": "<string>",
"referrer": "<string>",
"type": "<string>",
"user_agent": "<string>",
"title": "<string>"
} }
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
url: '<string>',
page_properties: {
client: {
url: '<string>',
domain: '<string>',
referrer: '<string>',
type: '<string>',
user_agent: '<string>',
title: '<string>'
}
}
})
};
fetch('https://api.permutive.com/ctx/v1/segment', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.permutive.com/ctx/v1/segment",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => '<string>',
'page_properties' => [
'client' => [
'url' => '<string>',
'domain' => '<string>',
'referrer' => '<string>',
'type' => '<string>',
'user_agent' => '<string>',
'title' => '<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.permutive.com/ctx/v1/segment"
payload := strings.NewReader("{\n \"url\": \"<string>\",\n \"page_properties\": {\n \"client\": {\n \"url\": \"<string>\",\n \"domain\": \"<string>\",\n \"referrer\": \"<string>\",\n \"type\": \"<string>\",\n \"user_agent\": \"<string>\",\n \"title\": \"<string>\"\n }\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.permutive.com/ctx/v1/segment")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"<string>\",\n \"page_properties\": {\n \"client\": {\n \"url\": \"<string>\",\n \"domain\": \"<string>\",\n \"referrer\": \"<string>\",\n \"type\": \"<string>\",\n \"user_agent\": \"<string>\",\n \"title\": \"<string>\"\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.permutive.com/ctx/v1/segment")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"<string>\",\n \"page_properties\": {\n \"client\": {\n \"url\": \"<string>\",\n \"domain\": \"<string>\",\n \"referrer\": \"<string>\",\n \"type\": \"<string>\",\n \"user_agent\": \"<string>\",\n \"title\": \"<string>\"\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"cohorts": {},
"activations": {},
"contextual_data": {}
}Contextual API
Get Contextual Segments
POST
/
ctx
/
v1
/
segment
Get Contextual Segments
curl --request POST \
--url https://api.permutive.com/ctx/v1/segment \
--header 'Content-Type: application/json' \
--data '
{
"url": "<string>",
"page_properties": {
"client": {
"url": "<string>",
"domain": "<string>",
"referrer": "<string>",
"type": "<string>",
"user_agent": "<string>",
"title": "<string>"
}
}
}
'import requests
url = "https://api.permutive.com/ctx/v1/segment"
payload = {
"url": "<string>",
"page_properties": { "client": {
"url": "<string>",
"domain": "<string>",
"referrer": "<string>",
"type": "<string>",
"user_agent": "<string>",
"title": "<string>"
} }
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
url: '<string>',
page_properties: {
client: {
url: '<string>',
domain: '<string>',
referrer: '<string>',
type: '<string>',
user_agent: '<string>',
title: '<string>'
}
}
})
};
fetch('https://api.permutive.com/ctx/v1/segment', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.permutive.com/ctx/v1/segment",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => '<string>',
'page_properties' => [
'client' => [
'url' => '<string>',
'domain' => '<string>',
'referrer' => '<string>',
'type' => '<string>',
'user_agent' => '<string>',
'title' => '<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.permutive.com/ctx/v1/segment"
payload := strings.NewReader("{\n \"url\": \"<string>\",\n \"page_properties\": {\n \"client\": {\n \"url\": \"<string>\",\n \"domain\": \"<string>\",\n \"referrer\": \"<string>\",\n \"type\": \"<string>\",\n \"user_agent\": \"<string>\",\n \"title\": \"<string>\"\n }\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.permutive.com/ctx/v1/segment")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"<string>\",\n \"page_properties\": {\n \"client\": {\n \"url\": \"<string>\",\n \"domain\": \"<string>\",\n \"referrer\": \"<string>\",\n \"type\": \"<string>\",\n \"user_agent\": \"<string>\",\n \"title\": \"<string>\"\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.permutive.com/ctx/v1/segment")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"<string>\",\n \"page_properties\": {\n \"client\": {\n \"url\": \"<string>\",\n \"domain\": \"<string>\",\n \"referrer\": \"<string>\",\n \"type\": \"<string>\",\n \"user_agent\": \"<string>\",\n \"title\": \"<string>\"\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"cohorts": {},
"activations": {},
"contextual_data": {}
}Retrieve contextual cohort codes for a given URL and page properties. Returns cohort codes formatted for Google Ad Manager.
Request
Query Parameters
string
required
Your Permutive API key. This is the same API key used for your main Permutive SDK deployment.
Body Parameters
string
required
The URL to retrieve contextual cohorts for. This is typically the current page URL.
object
required
An object containing page properties used for contextual classification. This should match the structure of properties you track in Pageview events, but must exclude any user-related data.
You can also include any custom page properties that you track as part of your Pageview events (e.g.,
Show page_properties structure
Show page_properties structure
object
category, tags, author).Personal Data: The request must not contain any user-related data points. Omit any user-related properties that you might be recording as part of your Pageview events.
Response
array of strings
All contextual cohort codes for the page. This is the complete list of cohorts that matched.
object
An object mapping activation destination names to arrays of cohort code strings. Each key is an activation destination (e.g.,
target_dfp, appnexus_adserver) and the value is an array of cohort codes configured for that destination.object
An object containing content classification data, returned when a classification provider is enabled in the account. Includes classifications such as categories, keywords, entities, sentiment, emotion, and concepts.
Example Request
curl -X POST "https://api.permutive.com/ctx/v1/segment?k=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/article/sports-news",
"page_properties": {
"client": {
"url": "https://example.com/article/sports-news",
"domain": "example.com",
"referrer": "https://example.com",
"type": "web",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
"title": "Latest Sports News"
},
"category": "sports",
"tags": ["football", "premier-league"]
}
}'
const apiKey = 'YOUR_API_KEY';
const url = `https://api.permutive.com/ctx/v1/segment?k=${apiKey}`;
const response = await fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
url: document.URL,
page_properties: {
client: {
url: document.URL,
domain: window.location.hostname,
referrer: document.referrer,
type: 'web',
user_agent: navigator.userAgent,
title: document.title
},
category: 'sports',
tags: ['football', 'premier-league']
}
})
});
const data = await response.json();
console.log(data);
let apiKey = "YOUR_API_KEY"
let requestUrl = URL(string: "https://api.permutive.com/ctx/v1/segment?k=\(apiKey)")!
let requestBody: [String: Any] = [
"url": "https://example.com/article/sports-news",
"page_properties": [
"client": [
"url": "https://example.com/article/sports-news",
"domain": "example.com",
"type": "ios",
"title": "Latest Sports News"
],
"category": "sports"
]
]
var request = URLRequest(url: requestUrl)
request.httpMethod = "POST"
request.httpBody = try? JSONSerialization.data(withJSONObject: requestBody)
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
URLSession.shared.dataTask(with: request) { data, response, error in
// Handle response
}.resume()
val apiKey = "YOUR_API_KEY"
val requestBody = ContextualBody(
page_properties = mapOf(
"client" to mapOf(
"url" to "https://example.com/article/sports-news",
"domain" to "example.com",
"type" to "android",
"title" to "Latest Sports News"
),
"category" to "sports"
),
url = "https://example.com/article/sports-news"
)
contextualApi.getContextualCohorts(apiKey, requestBody)
.enqueue(object : Callback<ContextualResponse> {
override fun onResponse(call: Call<ContextualResponse>, response: Response<ContextualResponse>) {
val cohorts = response.body()
// Handle response
}
override fun onFailure(call: Call<ContextualResponse>, t: Throwable) {
// Handle error
}
})
Example Response
{
"cohorts": ["abc", "def", "ghi"],
"activations": {
"target_dfp": ["abc", "def"],
"appnexus_adserver": ["ghi"]
},
"contextual_data": {
"classifications": {
"categories": [
{
"value": "155",
"confidence": 0.5,
"taxonomy": "iab_3.0",
"provider": "ibm_watson"
}
],
"keywords": [
{
"value": "museum",
"confidence": 0.7,
"provider": "ibm_watson"
}
],
"entities": [
{
"value": "British Museum",
"confidence": 0.9,
"provider": "ibm_watson"
}
],
"sentiment": [
{
"value": "positive",
"confidence": 0.9,
"provider": "ibm_watson"
}
],
"emotion": [
{
"value": "joy",
"confidence": 0.4,
"provider": "ibm_watson"
}
],
"concepts": [
{
"value": "Vincent van Gogh",
"confidence": 0.6,
"provider": "ibm_watson"
}
]
}
}
}
{
"cohorts": [],
"activations": {},
"contextual_data": {}
}
{
"error": "Invalid request body"
}
Implementation Notes
Always include 'rts' in targeting
Always include 'rts' in targeting
When passing targeting values to your ad server, always append
rts to the array of cohort codes. This is required for proper targeting:const targetingValues = apiResponse.activations.target_dfp.concat('rts');
Call early in page lifecycle
Call early in page lifecycle
Make the API call as early as possible when the page loads to ensure targeting is attached to the first ad call. We recommend placing the API call in the
<head> of your page.Use the same API key
Use the same API key
Use the same API key that you use for your main Permutive SDK deployment. This ensures cohorts are correctly associated with your workspace.
Related
Activating in Google Ad Manager
Full implementation guide with code samples for Google Ad Manager.
API Introduction
Overview of the Contextual API.
⌘I