Get Started - Text API

1 Text Analysis Endpoints
2 Example Text Request
3 Example Text JSON Response Body
4 More Information

Text Analysis Endpoints

The GumGum Contextual text analysis endpoints are:

HTTP Request	POST

HTTP Request	POST
Authorization Header	`X-api-key: value`
GumGum Contextual Endpoint	`https://verity-api.gumgum.com/text/classification`
Body	`{json example}`

HTTP Request	GET

HTTP Request	GET
Authorization Header	`X-api-key: value`
GumGum Contextual Endpoint	`https://verity-api.gumgum.com/text/classification/{uuid}`

HTTP Request	GET

HTTP Request	GET
Authorization Header	`X-api-key: value`
GumGum Contextual Endpoint	`https://verity-api.gumgum.com/text/classification/{uuid}/status`

Example Text Request

This example shows a request to analyze the following text string:

Kubernetes (also known as k8s or kube) is an open source container orchestration platform that automates many of the manual processes

{
"text":"Kubernetes (also known as k8s or kube) is an open source container orchestration platform that automates many of the manual processes",
"langaguageCode": "en",
"callbackUrl": "URL value"
}

Field	Requirement	Description

Field	Requirement	Description
text	Required	Text for the asset to process
languageCode	Required	Video description provided by client
callbackUrl	Optional	If provided, Verity will push Text Classification results to this endpoint after the text has processed successfully.

Step 1 – Submit a POST request via curl to /text/classification

Submit a POST request with the text string to be analyzed, for example:

curl -H 'x-api-key: <YOUR_API_KEY_HERE>' -H 'Content-Type: application/json' -X POST -d '{"text":"Kubernetes (also known as k8s or kube) is an open source container orchestration platform that automates many of the manual processes", "languageCode": "en"}'  https://verity-api.gumgum.com/text/classification

GumGum Contextual API returns a JSON response of Content-Type: application/json; charset=UTF-8 with a uuid for the request and current request status, for example:

{
  "uuid": "c7bcbe04-ea77-4808-8e91-28d325d1b1fc",
  "acceptedAt": "2020-06-25T23:09:41.729Z"
}

For a list of supported status messages, refer to Application Status Messages.

Once the image classification request was sent, if a callback url was provided results will be sent to the webhook endpoint.

Step 2 – Submit a GET request to /text/classification/{uuid}/status

Submit a GET request to /text/classification/{uuid}/status, specifying the uuid returned in the previous step. Within a short period, once analysis of the text is complete, a status change occurs. For example:

curl -H 'x-api-key: <YOUR_API_KEY_HERE>' https://verity-api.gumgum.com/text/classification/c7bcbe04-ea77-4808-8e91-28d325d1b1fc/status

GumGum Contextual API returns a JSON response showing the request has the following status:

{
  "uuid" : "c7bcbe04-ea77-4808-8e91-28d325d1b1fc",
  "status": "ANALYZING"
}

Step 3 – Submit a GET request to /text/classification/{uuid}

Submit a GET request to /text/classification/{uuid}, specifying the uuid returned in the response in Step 1 to get the results. This endpoint will not return status and will only return results once the status changes to PROCESSED otherwise will return '404 - Not Found'. The JSON text classification results are returned in the data payload.

curl -H 'x-api-key: <YOUR_API_KEY_HERE>' https://verity-api.gumgum.com/text/classification/c7bcbe04-ea77-4808-8e91-28d325d1b1fc

Example Text JSON Response Body

{
  "uuid": "28b82df1-452d-5054-875d-556abbac5f1b",
  "data": {
    "processedAt": "2021-06-06T08:22:24.097Z",
    "expiresAt": "2021-07-06T08:22:24.097Z",
    "iab": {
      "v2": [
        {
          "id": "596",
          "category": "Technology & Computing",
          "score": 0.59
        },
        {
          "id": "620",
          "category": "Cloud Computing",
          "score": 0.21,
          "parent": {
            "id": "619",
            "category": "Internet",
            "parent": {
              "id": "599",
              "category": "Computing",
              "parent": {
                "id": "596",
                "category": "Technology & Computing"
              }
            }
          }
        },
        {
          "id": "602",
          "category": "Computer Software and Applications",
          "score": 0.15,
          "parent": {
            "id": "599",
            "category": "Computing",
            "parent": {
              "id": "596",
              "category": "Technology & Computing"
            }
          }
        }
      ]
    },
    "keywords": [
      "kube",
      "k8s",
      "open source container orchestration platform",
      "kubernetes",
      "manual processes"
    ],
    "safe": true,
    "threats": [],
    "sentiments": [
      {
        "sentiment": "neutral",
        "score": 1
      },
      {
        "sentiment": "negative",
        "score": 0
      },
      {
        "sentiment": "positive",
        "score": 0
      }
    ]
  }
}

The JSON response details the complete brand safety, keyword, and categorization analysis data for the text. See JSON Response for details about the fields included in the response.