...
| Excerpt |
|---|
Verity |
...
GET /page/classify
Verity API processes HTTPS GET requests specifying a properly-formed page URL in the following format:
https://verity-api.gumgum.com/page/classify?pageUrl=<WEBPAGE_URL>
The URL specified in <WEBPAGE_URL> must meet the following requirements:
Start with http:// or https://.
Have a properly URL-encoded address.
Any request parameter values must be properly URL-encoded.
Example Page Request
Classifying the page with the Verity API is a simple two-step process. This example shows a request to analyze a web page, including its text and any prominent image detected. The example page URL is:
https://aragonresearch.com/cisco-google-and-zoom-enhance-free-meetings-to-assist-with-coronavirus
Step 1 – Submit a GET page classification request
To start the page analysis, submit a GET request via curl:
curl -H 'x-api-key: <YOUR_API_KEY_HERE>’ `https://verity-api.gumgum.com/page/classify?pageUrl=https%3A%2F%2Faragonresearch.com%2Fcisco-google-and-zoom-enhance-free-meetings-to-assist-with-coronavirus%2F` |
Verity API returns a JSON response with Content-Type: application/json; charset=UTF-8 showing the request has the following status:
{ "dataAvailable" : false, "status" : "INITIATED", "pageUrl" : "https://aragonresearch.com/cisco-google-and-zoom-enhance-free-meetings-to-assist-with-coronavirus" } |
For a list of supported status messages, refer to Application Status Codes.
Step 2 – Poll the endpoint
Poll the same endpoint specified in Step 1. Within a short period, once analysis of the page and its associated image is complete, a status change occurs and the returned message updates to:
{ "dataAvailable" : true, "status" : "PROCESSED", "pageUrl" : "https://aragonresearch.com/cisco-google-and-zoom-enhance-free-meetings-to-assist-with-coronavirus" } |
Once the status changes to PROCESSED, the JSON page classification results are returned in the response message data payload.
Note: You can also specify a callBackUrl in a GET request. The JSON classification results are then returned only to the callBackUrl, and not the response message data payload. See Integrating a Webhook for an example GET request with a callBackUrl.
Example Page JSON Response Body
The JSON response details the complete brand safety, keyword, and categorization analysis data for the page and its any prominent image detected. See JSON Response for details about the fields included in the response.
{ "dataAvailable": true, "status": "PROCESSED", "pageUrl": "https://aragonresearch.com/cisco-google-and-zoom-enhance-free-meetings-to-assist-with-coronavirus/", "verityData": { "languageCode": "en", "iab": { "v1": [ { "id": "IAB19", "category": "Technology & Computing", "score": 0.6 }, { "id": "IAB19-8", "category": "Computer Networking", "score": 0.13 }, { "id": "IAB19-23", "category": "Net Conferencing", "score": 0.11 }, { "id": "IAB19-18", "category": "Internet Technology", "score": 0.11 } ], "v2": [ { "id": "596", "category": "Technology & Computing", "score": 0.66 }, { "id": "607", "category": "Web Conferencing", "score": 0.12, "parent": { "id": "602", "category": "Computer Software and Applications", "parent": { "id": "599", "category": "Computing", "parent": { "id": "596", "category": "Technology & Computing" } } } }, { "id": "600", "category": "Computer Networking", "score": 0.09, "parent": { "id": "599", "category": "Computing", "parent": { "id": "596", "category": "Technology & Computing" } } }, { "id": "602", "category": "Computer Software and Applications", "score": 0.08, "parent": { "id": "599", "category": "Computing", "parent": { "id": "596", "category": "Technology & Computing" } } } ] }, "keywords": [ "cisco", "zoom", "google", "logmein", "coronavirus", "enhance", "meetings", "assist", "free", "and", "china", "jim lundy", "customers like zoom", "rise in", "aragon" ], "safe": true, "threats": [], "events": [], "sentiments": [ { "sentiment": "neutral", "score": 0.71 }, { "sentiment": "positive", "score": 0.26 }, { "sentiment": "negative", "score": 0.03 } ] } } |
How to Integrate a Webhook for Page Requests
To avoid continually polling the Verity Page endpoint for classification responses, clients can create a webhook to listen for results on a Verity callback URL.
To integrate with Verity, the webhook target server must:
Be able to receive HTTP/HTTPS POST requests over the internet.
Respond to Verity with an HTTP 2XX status code.
Send responses to Verity within 5 seconds.
Note: No data is required in webhook responses to Verity.
These steps walk through a Verity page classification request with webhook integration.
Step 1 – Expose web service
First, expose your web service, for example:
Step 2 – Create page classification request
Create a Verity page classification request, for example:
Step 3 – Add callbackUrl parameter with webhook address
Add a callBackUrl parameter with the webhook address to the page request. The webhook URL must be properly URL-encoded. For example:
&callBackUrl=https%3A%2F%2Fverity-webhook.domain.com%2Fresults |
Step 4 – Submit GET page classification request
Submit the GET request via curl:
curl -H 'x-api-key: <YOUR_API_KEY_HERE>’ `https://verity-api.gumgum.com/page/classify?pageUrl=https%3A%2F%2Ftest.iab12.com%2F1&callBackUrl=https%3A%2F%2Fverity-webhook.domain.com%2Fresults` |
...
Note: Verity response time SLAs are under development.
Step 5 – Verity POSTs response to webhook URL
After successfully processing the request, Verity initiates an HTTP/HTTPS POST to the webhook URL with the response JSON data, for example:
{
"dataAvailable": true,
"status": "PROCESSED",
"pageUrl": "https://aragonresearch.com/cisco-google-and-zoom-enhance-free-meetings-to-assist-with-coronavirus",
"verityData": {
"languageCode": "en",
"iab": {
"v1": [
{
"id": "IAB19",
"category": "Technology & Computing",
"score": 0.58
},
{
"id": "IAB19-23",
"category": "Net Conferencing",
"score": 0.15
},
{
"id": "IAB19-8",
"category": "Computer Networking",
"score": 0.12
},
{
"id": "IAB19-18",
"category": "Internet Technology",
"score": 0.1
}
],
"v2": [
{
"id": "596",
"category": "Technology & Computing",
"score": 0.45
},
{
"id": "52",
"category": "Business and Finance",
"score": 0.29
},
{
"id": "607",
"category": "Web Conferencing",
"score": 0.1,
"parent": {
"id": "602",
"category": "Computer Software and Applications",
"parent": {
"id": "599",
"category": "Computing",
"parent": {
"id": "596",
"category": "Technology & Computing"
}
}
}
},
{
"id": "600",
"category": "Computer Networking",
"score": 0.06,
"parent": {
"id": "599",
"category": "Computing",
"parent": {
"id": "596",
"category": "Technology & Computing"
}
}
},
{
"id": "53",
"category": "Business",
"score": 0.05,
"parent": {
"id": "52",
"category": "Business and Finance"
}
}
]
},
"keywords": [
"covid",
"coronavirus",
"covid-19",
"pandemic",
"logmein",
"coronavirus cisco",
"large coronavirus outbreak",
"cisco",
"zoom",
"logmein offers free remote",
"free webex cisco",
"google hangouts",
"google",
"cisco makes",
"aragon",
"zoom removes",
"google offers premium features",
"zoom enhance free meetings",
"enhance"
],
"safe": false,
"threats": [
{
"id": "GGT9",
"category": "Medical",
"confidence": "HIGH"
}
],
"events": [],
"sentiments": [
{
"sentiment": "neutral",
"score": 0.73
},
{
"sentiment": "positive",
"score": 0.24
},
{
"sentiment": "negative",
"score": 0.03
}
],
"processedAt": "2020-10-01T01:15:09.982Z"
}
}
Step 6 – Webhook target server sends a successful response status code
The webhook target server sends a successful response status code (2XX) within the HTTP connection timeout of 5 seconds.
The webhook target server is responsible for storing and managing the Verity response on the client platform.
Invalid Page Request Handling
The Verity API checks for malformed HTTP requests, such as:
Incomplete URLs.
Missing HTTP headers.
Invalid domain-specific information.
Example errors or invalid requests are as follows:
Example Error | { "dataAvailable": false, "Status": "ERROR", "pageUrl": "http://gg.error/1" } |
Example Invalid Request | { "dataAvailable": false, "Status": "INVALID", "pageUrl": "://gg.invalid/1" } |
...
page analysis involves scanning and analyzing both text and prominent imagery on a web page. Verity returns a page analysis response that includes IAB contextual categories, keywords, sentiment evaluation, and brand safety scoring. Brand safety scoring includes an overall Safe/Unsafe flag, plus classifications for multiple threat categories defined by GumGum (including drugs, weapons, and sexual content). |
How Page Analysis Works
Verity page analysis works by extracting metadata and significant content from a page, then applying computer vision (CV) and natural language processing (NLP) to the extracted data. For detailed information about Verity technology and processing, refer to the Verity Description of Methodology.
Note: Verity does not download or analyze the CSS, JavaScript, navigation, footer, sidebars, third-party ads, user-generated content, or other areas extraneous to the main textual content of the page.
Page Analysis Response
The Verity page analysis response is aggregated into the following sections:
IAB Categories
Identifies and scores contextual targeting categories. Includes standard IAB categories.Keywords
Extracts and scores page keywords according to prominence.Brand Safety
Identifies and scores brand safety threats according to GumGum's Threat classification taxonomy, in compliance with GARM’s Brand Safety Floor & Suitability Framework.Sentiments
Analyzes the overall opinions expressed within the content of a page, and classifies the percentage of positive, negative, and neutral sentiments.
The format is JavaScript Object Notation (JSON) Content-Type: application/json; charset=UTF-8.
Check out an example page analysis response here.
Page Analysis Categories and Keywords
The following table summarizes the classifications and keywords that are returned during page analysis.
Brand Safety (Threat) Categories | Contextual | Keywords |
|---|---|---|
Violence | Sentiment | Contextual targeting keywords |
Related Articles
| Filter by label (Content by label) | ||||||||
|---|---|---|---|---|---|---|---|---|
|