Content

Get a list of topics in the content graph. Topics are ordered by that occur on the most documents will be returned first.

curl -s -H "Authorization: $LIOKEY" \
 -XGET "https://api.lytics.io/api/content/topic" | jq '.'

Content-Type: application/json

{
  "status": 200,
  "message": "success",
  "data": [
    {
      "label": "Data-First Marketing",
      "doc_count": 275,
      "total": 380636,
      "missing": 216048,
      "present": 143710,
      "avg": 0.5983867964798089,
      "tags": [
        "custom"
      ]
    },
    {
      "label": "User Data Unification",
      "doc_count": 273,
      "total": 380636,
      "missing": 216048,
      "present": 154068,
      "avg": 0.6036863622558337,
      "tags": [
        "custom"
      ]
    },
    {
      "label": "Customer Data Platform",
      "doc_count": 313,
      "total": 380260,
      "missing": 216043,
      "present": 159628,
      "avg": 0.9704200631406573,
      "tags": [
        "custom"
      ]
    }
  ]
}

Get list of topic rollups.

curl "$LIOAPI/api/content/topicrollup" -s -H "Authorization: $LIOKEY" | jq '.'

Content-Type: application/json

{
    "data": [
        {
            "id": "6a7f76ff97ad0e3e96c162f74aee8f8f",
            "account_id": "2b15cafb441e477cad3ffbe62c4d5966",
            "label": "Baking rollup",
            "created": "2014-08-04T21:18:20.124Z",
            "updated": "2014-08-04T21:18:20.124Z",
            "topics": [
              {
                "label": "Recipe",
                "value": 0.66
              },
              {
                "label": "baking",
                "value": 0.55
              }
            ]
        }
    ]
}

Fetch a topic rollup by id

Content-Type: application/json

{
  "data": {
    "id": "6a7f76ff97ad0e3e96c162f74aee8f8f",
    "account_id": "2b15cafb441e477cad3ffbe62c4d5966",
    "label": "Baking rollup",
    "created": "2014-08-04T21:18:20.124Z",
    "updated": "2014-08-04T21:18:20.124Z",
    "topics": [
      {
        "label": "Recipe",
        "value": 0.66
      },
      {
        "label": "baking",
        "value": 0.55
      }
    ]
  }
}

Topic Rollups can be created with a variety of different configurations. To determine the right configuration for you, please consult the following examples:

Suppose the topic-affinities (lytics_content) for a given user is defined as:

{
  "Chex Mix": 0.5,
  "Cheetos": 0.3,
  "Pretzel": 0.2
}

1) Overwriting Topic Affinities

// topic rollup
{
  "overwrite": "replace",
  "label": "Snacks",
  "topics": [
    {
      "label": "Cheetos",
      "value": 1.0
    },
    {
      "label": "Chex Mix",
      "value": 1.0
    }
  ]
}

// topic affinites for user: 
{
  "Snacks": 0.4,
  "Pretzel": 0.2
}

2) Add to Topic Affinities

// topic rollup
{
  "overwrite": "append",
  "label": "Snacks",
  "topics": [
    {
      "label": "Cheetos",
      "value": 1.0
    },
    {
      "label": "Chex Mix",
      "value": 1.0
    }
  ]
}

// topic affinites for user: 
{
  "Snacks": 0.4,
  "Chex Mix": 0.5,
  "Cheetos": 0.3,
  "Pretzel": 0.2
}

Creating new Topic Rollups:

curl -s -XPOST "https://api.lytics.io/api/content/topicrollup" \
    -H "Content-type: application/json" \
    -H "Authorization: $LIOKEY" \
    -d'
{
  "label": "Baking rollup",
  "acctid": "123456",
  "topics": [
      {"label": "Recipe"},
      {"label": "baking"}
  ]
}
' | jq '.'

Content-Type: application/json

{
  "data": {
    "id": "6a7f76ff97ad0e3e96c162f74aee8f8f",
    "account_id": "2b15cafb441e477cad3ffbe62c4d5966",
    "label": "Baking rollup",
    "created": "2014-08-04T21:18:20.124Z",
    "updated": "2014-08-04T21:18:20.124Z",
    "topics": [
      {
        "label": "Recipe",
        "value": 0.66
      },
      {
        "label": "baking",
        "value": 0.55
      }
    ]
  }
}

Delete a topic rollup

Fetch the blocklisted topics

Content-Type: application/json

  {
    "status": 200,
    "message": "success",
    "data": [
      {
        "label": "Data-First Marketing",
        "doc_count": 275,
        "total": 380636,
        "missing": 216048,
        "present": 143710,
        "avg": 0.5983867964798089,
        "tags": [
          "blocklisted"
        ]
      },
      {
        "label": "User Data Unification",
        "doc_count": 273,
        "total": 380636,
        "missing": 216048,
        "present": 154068,
        "avg": 0.6036863622558337,
        "tags": [
          "blocklisted"
        ]
      }
    ]
  }

Blocklist or un-blocklist topics to an account's topic-blocklist

# to blocklist certain topics
curl -s -XPOST "https://api.lytics.io/api/content/topicblocklist" \
    -H "Content-type: application/json" \
    -H "Authorization: $LIOKEY" \
    -d'
{
  "method": "add",
  "ids": ["Data-First Marketing", "User Data Unification"]
}
' | jq '.'

# to unblocklist certain topics
curl -s -XPOST "https://api.lytics.io/api/content/topicblocklist" \
    -H "Content-type: application/json" \
    -H "Authorization: $LIOKEY" \
    -d'
{
  "method": "delete",
  "ids": ["Data-First Marketing", "User Data Unification"]
}
' | jq '.'

Content-Type: application/json

  {
    "status": 200,
    "message": "success",
    "data": [
      {
        "label": "Data-First Marketing",
        "doc_count": 275,
        "total": 380636,
        "missing": 216048,
        "present": 143710,
        "avg": 0.5983867964798089,
        "tags": [
          "blocklisted"
        ]
      },
      {
        "label": "User Data Unification",
        "doc_count": 273,
        "total": 380636,
        "missing": 216048,
        "present": 154068,
        "avg": 0.6036863622558337,
        "tags": [
          "blocklisted"
        ]
      }
    ]
  }

Replace topics in an account's topic-blocklist

curl -s -XPOST "https://api.lytics.io/api/content/topicblocklist" \
    -H "Content-type: application/json" \
    -H "Authorization: $LIOKEY" \
    -d'
{
  "ids": ["Data-First Marketing", "User Data Unification"]
}
' | jq '.'

Content-Type: application/json

  {
    "status": 200,
    "message": "success",
    "data": [
      {
        "label": "Data-First Marketing",
        "doc_count": 275,
        "total": 380636,
        "missing": 216048,
        "present": 143710,
        "avg": 0.5983867964798089,
        "tags": [
          "blocklisted"
        ]
      },
      {
        "label": "User Data Unification",
        "doc_count": 273,
        "total": 380636,
        "missing": 216048,
        "present": 154068,
        "avg": 0.6036863622558337,
        "tags": [
          "blocklisted"
        ]
      }
    ]
  }

Add a document to the content table corpus. Either a URL or text must be provided. This allows entry of documents/content that get added to content table, content-graph and available for usage in recommendation, as well as content-explorer.

• id if you upload the document more than once, ensure it has common id so only one document is created

• Custom Attributes Any attributes you upload that are not reserved, will be added to content document.

# Upsert a document into content table and classify it
curl -s -XPOST "https://api.lytics.io/api/content/corpus" \
  -H "Authorization: $LIOKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id":"doc_id_123",
    "text":"big-long-body-of text for classification",
    "custom_attribute_name":"custom attribute"
}' | jq '.'

# upsert a url into db
#  url is used as document id
curl -s -XPOST "https://api.lytics.io/api/content/corpus" \
  -H "Authorization: $LIOKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url":"http://www.validdomain/validurl.html",
    "custom_attribute_name":"custom attribute"
}' | jq '.'

Content-Type: application/json

{
    "status": 200,
    "message": "success",
    "data": {
        "body": "here is some body text for the Corpus API",
        "source": "upload",
        "updated": "2016-09-13 21:59:38.551972802 -0400 EDT",
        "created": "2016-09-13 21:59:38.551972802 -0400 EDT",
        "url": "https://www.getlytics.com/blog/post/improving_google_analytics?utm_source=linkedin",
        "global": {
            "Topic A": 1.0,
            "Topic B": 1.0
        }
     }
}

Add a topic to a Document. Note that while this API will add the topic to a Document, it may take several days or the topic to appear in a users's topic-affinity.

# Add a topic to a document
curl -s -XPOST "https://api.lytics.io/api/content/doc/hashedurl/4525087172572165639/topic/Chocolate?relevance=1.0" \
  -H "Authorization: $LIOKEY" \
| jq '.'

Content-Type: application/json

{
    "status": 200,
    "message": "success",
    "data": {
        "author": "Cookie Monster",
        "created": "2016-01-14T08:39:01.354824186-07:00",
        "description": "you should definitely make these cookies",
        "fetched": "2016-07-19T13:39:20.158747984-04:00",
        "id": "4525087172572165639",
        "meta": [
            "og:locale/en_US"
        ],
        "primary_image": "http://cookdiary.net/wp-content/uploads/images/Oatmeal-Chocolate-Chip-Cookies_1441.jpg",
        "stream": "default",
        "title": "how to make some cookies",
        "topic_relevances": {
            "Recipe": 0.64,
            "baking": 0.75
        },
        "topic_rollups": {
            "Things": 0.75
        },
        "topics": [
            "baking",
            "Recipe"
        ],
        "updated": "2016-07-19T13:34:18-04:00",
        "url": "www.recipes.com/chocolate-chip-cookies"
    }
}

Remove a topic from a Document. Note that while this API will remove the topic from a Document, it may take several days for the topic to be removed from a user's topic-affininty.

# Remove a topic from a document
curl -s -XDELETE "https://api.lytics.io/api/content/doc/hashedurl/4525087172572165639/topic/Recipe" \
  -H "Authorization: $LIOKEY" \
| jq '.'

Fetch an Affinity Config by id

Content-Type: application/json

{
    "data": {
        "account_id": "c48add61e37e459b9abdb7c0784aa463",
        "aid": 123,
        "created": "2021-05-13T21:18:57.115Z",
        "decay_affinities": false,
        "explicit_affinities": false,
        "hash_ids": false,
        "id": "8dd1fe8ba134a6b5a41061a5661da7f9",
        "inferred_affinities": false,
        "invalid": false,
        "lhs_node_id": "product_ids",
        "lhs_output_id": "product_affinities",
        "lhs_table": "user",
        "limit_affinities": 50,
        "num_topics": 500,
        "rhs_feature_id": "attributes",
        "rhs_node_id": "sku",
        "rhs_table": "product",
        "updated": "2021-05-13T21:18:57.115Z"
    }
}

Affinity Configs can be created with a variety of different configurations. To determine the right configuration for you, please contact Support or reach out to your account manager:

1) Creating an Affinity Config for Product data:

echo '{
    "account_id": "c48add61e37e459b9abdb7c0784aa463",
    "aid": 123,
    "lhs_node_id": "viewed_product_ids",
    "lhs_output_id": "product_affinities",
    "lhs_table": "user",
    "rhs_feature_id": "product_attributes",
    "rhs_node_id": "product_id",
    "rhs_table": "product"
}' | http POST 'https://api.lytics.io/api/content/config?key=<your_key>'

2) Creating an Affinity Config based on Content data:

echo '{
    "account_id": "c48add61e37e459b9abdb7c0784aa463",
    "aid": 123,
    "lhs_node_id": "hashedurls",
    "lhs_output_id": "author_affinities",
    "lhs_table": "user",
    "rhs_feature_id": "author_names",
    "rhs_node_id": "hashedurl",
    "rhs_table": "content",
    "explicit_affinities": true
}' | http POST 'https://api.lytics.io/api/content/config?key=<your_key>'

Content-Type: application/json

{
    "data": {
        "account_id": "c48add61e37e459b9abdb7c0784aa463",
        "aid": 123,
        "created": "2021-05-13T21:18:57.115Z",
        "decay_affinities": false,
        "explicit_affinities": false,
        "hash_ids": false,
        "id": "8dd1fe8ba134a6b5a41061a5661da7f9",
        "inferred_affinities": false,
        "invalid": false,
        "lhs_node_id": "product_ids",
        "lhs_output_id": "product_affinities",
        "lhs_table": "user",
        "limit_affinities": 50,
        "num_topics": 500,
        "rhs_feature_id": "attributes",
        "rhs_node_id": "sku",
        "rhs_table": "product",
        "updated": "2021-05-13T21:18:57.115Z"
    }
}

Edit an Affinity Config:

Examples:

curl -s -XPUT "https://api.lytics.io/api/content/config/123456id" \
    -H "Authorization: $LIOKEY" \
    -H "Content-type: application/json" \
    -d'
{
    "label": "New Affinity Config Label",
    "rhs_feature_id": "purchased_product_ids",
    "description": "New Affinity Config description"
}
' | jq '.'

Content-Type: application/json

{
    "data": {
        "account_id": "c48add61e37e459b9abdb7c0784aa463",
        "aid": 123,
        "created": "2021-05-13T21:18:57.115Z",
        "decay_affinities": false,
        "explicit_affinities": false,
        "hash_ids": false,
        "id": "8dd1fe8ba134a6b5a41061a5661da7f9",
        "inferred_affinities": false,
        "invalid": false,
        "lhs_node_id": "product_ids",
        "lhs_output_id": "product_affinities",
        "lhs_table": "user",
        "limit_affinities": 50,
        "num_topics": 500,
        "rhs_feature_id": "attributes",
        "rhs_node_id": "sku",
        "rhs_table": "product",
        "updated": "2021-05-13T21:18:57.115Z"
    }
}

Delete an Affinity Config

Fetch Affinity by id; can specify optional parameters: 1) config to pass in an already created associated Affinity Config or 2) sideload objects to sideload

Content-Type: application/json

{
    "data": {
        "aid": 123,
        "author_id": "123abc",
        "config_id": "ced87531cfbc5a4fd1ff1df2fe0150eb",
        "created": "2021-05-14T23:04:34.351Z",
        "description": "An affinity for marketing",
        "id": "b7f97cf6237b97f8a83b4a2c1f8370be",
        "label": "marketing",
        "method": "document",
        "slug": "marketing",
        "topics": [
            {
            "label": "Customer Data Platform",
            "value": 1.0
            },
            {
            "label": "User Data Unification",
            "value": 1.0
            }
        ],
        "updated": "2021-05-14T23:04:34.351Z"
    }
}

Affinities can be created with a variety of different configurations. To determine the right configuration for you, please contact Support or reach out to your account manager:

Creating a new Affinity

echo '{
    "aid": 123,
    "config_id": "ced87531cfbc5a4fd1ff1df2fe0150eb",
    "label": "marketing",
    "slug": "marketing",
    "description": "An affinity for marketing",
    "method": "document",
    "topics": [
        {"label": "Customer Data Platform"},
        {"label": "User Data Unification"}
    ]
}' | http POST 'https://api.lytics.io/api/content/affinity/?key=<your_key>'

Content-Type: application/json

{
    "data": {
        "aid": 123,
        "author_id": "123abc",
        "config_id": "ced87531cfbc5a4fd1ff1df2fe0150eb",
        "created": "2021-05-14T23:04:34.351Z",
        "description": "An affinity for marketing",
        "id": "b7f97cf6237b97f8a83b4a2c1f8370be",
        "label": "marketing",
        "method": "document",
        "slug": "marketing",
        "topics": [
            {
            "label": "Customer Data Platform",
            "value": 1.0
            },
            {
            "label": "User Data Unification",
            "value": 1.0
            }
        ],
        "updated": "2021-05-14T23:04:34.351Z"
    }
}

Edit an Affinity:

curl -s -XPUT "https://api.lytics.io/api/content/affinity/b7f97cf6237b97f8a83b4a2c1f8370be" \
    -H "Authorization: $LIOKEY" \
    -H "Content-type: application/json" \
    -d'
{
    "label": "New Affinity Label",
    "method": "new method",
    "description": "New Affinity description"
}
' | jq '.'

{
    "data": {
        "aid": 123,
        "author_id": "123abc",
        "config_id": "ced87531cfbc5a4fd1ff1df2fe0150eb",
        "created": "2021-05-14T23:04:34.351Z",
        "description": "New Affinity description",
        "id": "b7f97cf6237b97f8a83b4a2c1f8370be",
        "label": "New Affinity Label",
        "method": "new method",
        "slug": "marketing",
        "topics": [
            {
            "label": "Customer Data Platform",
            "value": 1.0
            },
            {
            "label": "User Data Unification",
            "value": 1.0
            }
        ],
        "updated": "2021-05-14T23:51:21.78Z"
    }
}

Delete an Affinity