Developing with Lytics / Lytics API Documentation

Content

Content APIs for Lytics Content Affinity Engine, allow for adding content into lytics, getting lists of content, and understanding the content and content-topics.

Content Classification Content classification refers to the Lytics automated process of taking text, URL, image based content and classifying it to attach topics to content documents.

  • Content A list of content (URLs, Email Documents, Uploaded Documents, Campaigns) and the topics, created dates, etc for each.

  • Content Topics Categories/Topics are applied to each piece of content.

  • User Content Affinity Based on user interacting with content, the topics (derived from the content they interact with) is enriched into their profile.

First, an overview of How this content gets here.

  • Observed URLs Once the lytics tag is on a Website, as users use the website any new URL they interact with is collected.

  • Crawling we can proactively crawl a site.

  • Email Tools We see URLs inside of email campaigns and proactively classify those URLs, as well as the emails themselves.

  • Uploaded Content You may upload content to the Classify.

Use Cases

1) User Content Recomendations Find content for a user based on their content-affinity.

2) Get List of Content Rich query api to get content.

Examples

# ad-hoc segment scan from content table
# get a list of content documents that
#  - have aspects=article   (aspects = article,product, etc)
#  - has imageurl
curl -s -H "Authorization: $LIOKEY" \
 -XGET "https://api.lytics.io/api/segment/scan?sortfield=created&limit=10" -d '
FILTER AND (
 EXISTS imageurls
 aspects = "article"
)
FROM content
' | jq '.'

# Create a content-segment
# - uses "ALIAS" as id for create/update, must be unique
curl -s -H "Authorization: $LIOKEY" -H "Content-Type: text/plain" \
  -XPOST "$LIOAPI/api/segment" -d '
FILTER AND (
 EXISTS imageurls
 aspects = "article"
)
FROM content
WITH name = "My Articles"
ALIAS my_articles
' | jq '.'

# grab just those content-docs using named segment scan
curl -s -H "Authorization: $LIOKEY" \
 -XGET "https://api.lytics.io/api/segment/my_articles/scan?sortfield=created&limit=10" \
  | jq '.'


# grab recommended articles for single user
curl -s -H "Authorization: $LIOKEY" \
 -XGET "https://api.lytics.io/api/content/recommend/:your_account_id/user/user_id/123456" \
  | jq '.'

Content Topics

/api/content/topic{?limit}

Get a list of topics in the content graph.

Parameters
limitint (optional)
Ex: 20
limit on number of topics to return, default = 500
GET

Content Topics

/api/content/topic{?limit}

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?limit=10" | jq '.'

Response 200

Headers
Content-Type: application/json
Body
{
  "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"
      ]
    }
  ]
}

Content Topic Summary

/api/content/topic/{topic}

Get a summary of user affinity for, and related documents to a topic.

For each given topic, find out how many users have a high, low, none affinity for a given topic.

GET

Content Topic Summary

/api/content/topic/{topic}

Response 200

Headers
Content-Type: application/json
Body
{
    "status": 200,
    "message": "success",
    "data": {
       "topics": {
            "total": 3232717,
            "missing": 2985477,
            "present": 239239,
            "bucket_none": 8001,
            "bucket_low": 26279,
            "bucket_mid": 11742,
            "bucket_high": 201218,
            "avg": 0.90787879293533
        },
        "docs": {
            "total": 373,
            "urls": [
                {
                    "url": "www.our-site.com/product/new-product-xyz",
                    "title": "Blue Running Shoes that make you faster",
                    "topics": [
                        "our-site (company)",
                        "running",
                        "shoes"
                    ],
                    "id": "3395466611293777389"
                }
            ]
        }
    }
}

Content Topic Rollup Summary

/api/content/rollup/{label}

High-level categories can be expressed as Topic Rollups. Topic rollups are user defined, and can simplify your interactions with using content for personalization and recommendation. Topics and rollups share a many-to-many relationships topic rollups should have multiple low-level topics and low-level topics can subscribe to multiple topic rollups.

GET

Content Topic Rollup Summary

/api/content/rollup/{label}

Response 200

Headers
Content-Type: application/json
Body
{
    "data": {
        "docs": {
            "total": 2,
            "urls": [
                {
                    "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"
                },
                {
                    "author": "The Swedish Chef",
                    "created": "2016-07-19T13:39:20.158747984-04:00",
                    "description": "a delicious cake",
                    "id": "-2119104978705508335",
                    "primary_image": "http://www.vanillacake.com/cake.jpg",
                    "stream": "default",
                    "title": "Basic Vanilla Cake Recipe",
                    "topic_relevances": {
                        "Recipe": 0.64,
                        "baking": 0.85
                    },
                    "topic_rollups": {
                        "Desserts": 0.85
                    },
                    "topics": [
                        "Recipe",
                        "baking"
                    ],
                    "updated": "2016-07-19T13:29:18-04:00",
                    "url": "www.recipes.com/cake"
                }
            ]
        },
        "rollups": null
    },
    "message": "success",
    "status": 200
}

Content Topic Rollup List

/api/content/topicrollup

Get a list of all topic-rollups for an account. To retrieve a single topic-rollup, please refer to the Content Topic Rollup API.

GET

Content Topic Rollup List

/api/content/topicrollup

Get list of topic-rollups.

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

Response 200

Headers
Content-Type: application/json
Body
{
    "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
              }
            ]
        }
    ]
}

Content Topic Blacklist

/api/content/topicblacklist

Get a list of the blacklisted topics. Blacklisted topics will have the blacklisted identifier in the tags field.

GET

Content Topic Blacklist Fetch

/api/content/topicblacklist

Fetch the blacklisted topics

Response 200

Headers
Content-Type: application/json
Body
  {
    "status": 200,
    "message": "success",
    "data": [
      {
        "label": "Data-First Marketing",
        "doc_count": 275,
        "total": 380636,
        "missing": 216048,
        "present": 143710,
        "avg": 0.5983867964798089,
        "tags": [
          "blacklisted"
        ]
      },
      {
        "label": "User Data Unification",
        "doc_count": 273,
        "total": 380636,
        "missing": 216048,
        "present": 154068,
        "avg": 0.6036863622558337,
        "tags": [
          "blacklisted"
        ]
      }
    ]
  }
POST

Content Topic Blacklist Create

/api/content/topicblacklist

Blacklist or un-blacklist topics to an account's topic-blacklist

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

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

Response 200

Headers
Content-Type: application/json
Body
  {
    "status": 200,
    "message": "success",
    "data": [
      {
        "label": "Data-First Marketing",
        "doc_count": 275,
        "total": 380636,
        "missing": 216048,
        "present": 143710,
        "avg": 0.5983867964798089,
        "tags": [
          "blacklisted"
        ]
      },
      {
        "label": "User Data Unification",
        "doc_count": 273,
        "total": 380636,
        "missing": 216048,
        "present": 154068,
        "avg": 0.6036863622558337,
        "tags": [
          "blacklisted"
        ]
      }
    ]
  }
PUT

Content Topic Blacklist Update

/api/content/topicblacklist

Replace topics in an account's topic-blacklist

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

Response 200

Headers
Content-Type: application/json
Body
  {
    "status": 200,
    "message": "success",
    "data": [
      {
        "label": "Data-First Marketing",
        "doc_count": 275,
        "total": 380636,
        "missing": 216048,
        "present": 143710,
        "avg": 0.5983867964798089,
        "tags": [
          "blacklisted"
        ]
      },
      {
        "label": "User Data Unification",
        "doc_count": 273,
        "total": 380636,
        "missing": 216048,
        "present": 154068,
        "avg": 0.6036863622558337,
        "tags": [
          "blacklisted"
        ]
      }
    ]
  }

Content Topic Rollup

/api/content/topicrollup/{id}

Get single topic-rollup by ID

Parameters
idstring (required)
Ex: 123abc
id of topic-rollup
GET

Content Topic Rollup Fetch

/api/content/topicrollup/{id}

Fetch a topic-rollup by id

Response 200

Headers
Content-Type: application/json
Body
{
  "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
      }
    ]
  }
}
POST

Content Topic Rollup Create

/api/content/topicrollup/{id}

Create a topic-rollup.

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 '.'

Response 201

Headers
Content-Type: application/json
Body
{
  "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

Content Topic Rollup Delete

/api/content/topicrollup/{id}

Delete a topic-rollup

Response 204

Content Document

/api/content/doc{?urls,ids}

Get a summary for document. If no hashed url is specified, then return the 10 most recent urls. Summaries may include the following properties:

PropertyDescription
urlExternal location of the content source
titleContents of the title tag in the case of a URL. In the case of email, the contents of the subject line.
descriptionContents of the meta tag with the name property of description, og:description, or twitter:description.
topicsA set of strings identifying relevant topics in the content. Each topic can be mapped directly to a Wikidata entity.
topic_relevancesAn object containing each topic and its predicted relevance.
topic_rollupsAn object containing each topic rollup and its composite relevance.
primary_imageURL of the primary image in the content.
authorPlain-text name of the author.
createdDate of publication. If unavailable, defaults to the time it is fetched by Lytics.
idReverse domain name notation of the canonicalized value of the URL.
sitenamePlain-text name of the site.
streamName of the Lytics stream where the URL was observed.
pathPath of the URL.
aspectsContextual type of a URL. One of article, discussion, image, product, video, other.
languageHuman language of the content.
updatedDate the content was last updated. This usually corresponds to its enrichment date inside of Lytics.
fetchedDate when the content was retrieved by Lytics.
hashedurlHashed value of the input URL, used for identification within Lytics.
Parameters
urls[]string (optional)
Ex: http//www.getlytics.com/blog/post
url to look up
ids[]int64 (optional)
Ex: 123abc
hashed url or campaign id to look up
GET

Content Document

/api/content/doc{?urls,ids}

Response 200

Headers
Content-Type: application/json
Body
{
    "status": 200,
    "message": "success",
    "data": {
        "total": 1,
        "urls": [
            {
                  "url": "www.our-site.com/product/new-product-xyz",
                  "title": "Blue Running Shoes that make you faster",
                  "topics": [
                      "our-site (company)",
                      "running",
                      "shoes"
                  ],
                  "id": "3395466611293777389"
            }
        ]
    }
}

Content Classify

/api/content/doc/classify{?url,text,draft}

Classify the given url or text. This will enrich the given url/text to add tags to it, and add it to the content index.

The Data Upload api's would allow you to relate user's to these documents.

Parameters
urlstring (optional)
Ex: http://myurl
url to classify
textstring (optional)
Ex: my text
text to classify
draftboolean (optional)
Ex: true
if true, the classified content will not be added to the content index
POST

Content Classify

/api/content/doc/classify{?url,text,draft}

Response 200

Headers
Content-Type: application/json
Body
{  
  "data":{  
    "id":"https://www.getlytics.com/blog/post/improving_google_analytics?utm_source=linkedin",
    "url":{  
      "Params":{ },
      "Utm":{  
        "utm_campaign":null,
        "utm_content":null,
        "utm_medium":null,
        "utm_source":"linkedin",
        "utm_term":null
      },
      "UserInfo":null
    },
    "url_redirected_from":"",
    "description":"Stop Pretending Your Insights Are Actionable: Part 1, Google Analytics",
    "long_description":"Most analytics tools are used purely for insight discovery rather than empowering action. We explore how the Lytics analytics integrations focus on action and filling the some massive gaps traditional analytics tools miss.",
    "type":"web",
    "stream":"",
    "httpstatus":0,
    "humanLanguage":"en",
    "tags":[  
      {  
        "type":"meta",
        "id":"og:title",
        "value":"stop pretending your insights are actionable: part 1, google analytics",
        "source":"meta",
        "vocab":"lytics",
        "relevance":1
      },
      {  
        "type":"concept",
        "id":"Google_Analytics",
        "tax":[  
          "http://dbpedia.org/ontology/Company",
          "http://dbpedia.org/ontology/Website",
          "http://dbpedia.org/ontology/Work",
          "http://www.w3.org/2002/07/owl#Thing"
        ],
        "value":"Google Analytics",
        "source":"diffbot",
        "vocab":"dbpedia",
        "relevance":0.95
      }
    ],
    "flags":null,
    "images":[  
      {  
        "url":"https://www.getlytics.com/img/blog/defaults/developers.gif"
      }
    ],
    "primary_image":"https://www.getlytics.com/img/blog/defaults/developers.gif",
    "videos":null,
    "primary_video":"",
    "published":"2015-10-23T00:00:00Z",
    "author":"Mark Hayden",
    "numpages":0,
    "sitename":"Lytics",
    "productDescription":"",
    "brand":"",
    "price":"",
    "saveAmount":"",
    "productId":"",
    "created":"2016-06-24T21:20:43.421892991Z",
    "fetched":"2016-06-24T21:20:45.751844316Z",
    "updated":"2016-06-24T21:20:52.367247963Z",
    "enriched":{  
      "diffbot":"2016-06-24T21:20:52.367248438Z",
      "google":"1970-01-01T00:00:00Z",
      "meta":"2016-06-24T21:20:45.751852586Z",
      "textrazor":"1970-01-01T00:00:00Z"
    },
    "version":4
  },
  "message":"success",
  "status":200
}

Content Recommendation

/api/content/recommend/user/{fieldname}/{fieldval}?{limit,ql,contentsegment,shuffle,visited,topics,rank,wait,email,url}

Find suggested content for a user based on their known affinities.

Parameters
fieldnamestring (required)
Ex: email
field to use to identify a user
fieldvalstring (required)
Ex: [email protected]
unique identity
contentsegmentstring (required)
Ex: blog_content
id, or slug of a content-collection to filter content
limitint (optional)
Ex: 20
limit on number of documents to suggest/return
shufflebool (optional)
Ex: false
whether or not to shuffle the recommendation order
visitedbool (optional)
Ex: false
whether to show recommendations for content the user has already viewed
topics[]string (optional)
Ex: ["Marketing", "Analytics"]
if supplied, only allow recommendations on content with the specified topics
rankstring (optional)
Ex: affinity
Ranking method for order of recommendations. Must be one of "popular", "recent", or "affinity"
waitbool (optional)
Ex: true
Whether or not to wait for more complex user identities to resolve
emailstring (optional)
Ex: [email protected]
if the fieldname and fieldval are omitted, an email can be provided. This can be helpful for templating use-cases
urlstring (optional)
Ex: www.example.com
if url is provided, the recommendations will be based on the content topics associated with the provided URL
GET

Content Recommendation

/api/content/recommend/user/{fieldname}/{fieldval}?{limit,ql,contentsegment,shuffle,visited,topics,rank,wait,email,url}

Response 200

Headers
Content-Type: application/json
Body
{  
  "data":[  
    {  
      "url":"www.getlytics.com/blog/post/intent_through_content",
      "title":"Understanding User Intent Through Content",
      "description":"Customer Intent comes from understanding the connection between engagement and its contexts. Content modeling and affinity graphs makes interpretation of intent a lot easier. Learn how marketers can benefit from this.",
      "topics":[  
        "customer data platform",
        "data science",
        "content marketing",
        "personalization"
      ],
      "topic_relevances":{  
        "content marketing":1,
        "customer data platform":1,
        "data science":1,
        "personalization":1
      },
      "primary_image":"https://www.getlytics.com/img/blog/posts/intent_through_content/intent_through_content-bg.gif",
      "author":"",
      "created":"2016-06-08T16:11:45.599594093Z",
      "id":"-3435113786560588929",
      "sitename":"Lytics",
      "stream":"default",
      "path":[  
        "blog",
        "blog/post",
        "blog/post/intent_through_content"
      ],
      "aspects":[  
        "article"
      ],
      "language":"unknown",
      "updated":"2016-06-09T12:49:36.870359765Z",
      "fetched":"2016-06-09T12:49:35.812654441Z",
      "meta":[  
        "og:locale/en_us",
        "og:site_name/lytics",
        "og:title/understanding user intent through content",
        "og:type/article",
        "og:url/https://www.getlytics.com/blog/post/intent_through_content"
      ],
      "confidence":0.5916079783099615,
      "visited":true
    }
  ],
  "message":"success",
  "status":200
}

Public Content Recommendation

/api/content/recommend/{account}/user/{fieldname}/{fieldval}?{limit,ql,contentsegment,shuffle,visited,topics,rank,wait,email,url}

This API offers a public alternative to the default recommendation endpoint, intended for use on public websites. In lieu of embedding secure API credentials on a public web page making public HTTP requests, authentication is determined by matching the domain of the HTTP referrer with the domain specified for the account.

Parameters
accountstring (required)
Ex: 123
the account ID
fieldnamestring (required)
Ex: email
field to use to identify a user
fieldvalstring (required)
Ex: [email protected]
unique identity
contentsegmentstring (required)
Ex: blog_content
id, or slug of a content-collection to filter content
limitint (optional)
Ex: 20
limit on number of documents to suggest/return
shufflebool (optional)
Ex: false
whether or not to shuffle the recommendation order
visitedbool (optional)
Ex: false
whether to show recommendations for content the user has already viewed
topics[]string (optional)
Ex: ["Marketing", "Analytics"]
if supplied, only allow recommendations on content with the specified topics
rankstring (optional)
Ex: affinity
Ranking method for order of recommendations. Must be one of "popular", "recent", or "affinity"
waitbool (optional)
Ex: true
Whether or not to wait for more complex user identities to resolve
emailstring (optional)
Ex: [email protected]
if the fieldname and fieldval are omitted, an email can be provided. This can be helpful for templating use-cases
urlstring (optional)
Ex: www.example.com
if url is provided, the recommendations will be based on the content topics associated with the provided URL
GET

Public Content Recommendation

/api/content/recommend/{account}/user/{fieldname}/{fieldval}?{limit,ql,contentsegment,shuffle,visited,topics,rank,wait,email,url}

Response 200

Headers
Content-Type: application/json
Body
{  
  "data":[  
    {  
      "url":"www.getlytics.com/blog/post/intent_through_content",
      "title":"Understanding User Intent Through Content",
      "description":"Customer Intent comes from understanding the connection between engagement and its contexts. Content modeling and affinity graphs makes interpretation of intent a lot easier. Learn how marketers can benefit from this.",
      "topics":[  
        "customer data platform",
        "data science",
        "content marketing",
        "personalization"
      ],
      "topic_relevances":{  
        "content marketing":1,
        "customer data platform":1,
        "data science":1,
        "personalization":1
      },
      "primary_image":"https://www.getlytics.com/img/blog/posts/intent_through_content/intent_through_content-bg.gif",
      "author":"",
      "created":"2016-06-08T16:11:45.599594093Z",
      "id":"-3435113786560588929",
      "sitename":"Lytics",
      "stream":"default",
      "path":[  
        "blog",
        "blog/post",
        "blog/post/intent_through_content"
      ],
      "aspects":[  
        "article"
      ],
      "language":"unknown",
      "updated":"2016-06-09T12:49:36.870359765Z",
      "fetched":"2016-06-09T12:49:35.812654441Z",
      "meta":[  
        "og:locale/en_us",
        "og:site_name/lytics",
        "og:title/understanding user intent through content",
        "og:type/article",
        "og:url/https://www.getlytics.com/blog/post/intent_through_content"
      ],
      "confidence":0.5916079783099615,
      "visited":true
    }
  ],
  "message":"success",
  "status":200
}

Content Segment Recommendation

/api/content/recommend/segment/{segId}?{limit,contentsegment,shuffle,rank}

Find suggested content for a segment based on their known affinities.

Parameters
segIdstring (required)
Ex: smt_power
id, or slug of the user segment to recommend content
contentsegmentstring (optional)
Ex: blog_content
id, or slug of a content-collection segment to filter content
limitint (optional)
Ex: 20
limit on number of documents to suggest/return
shufflebool (optional)
Ex: false
whether or not to shuffle the recommendation order
rankstring (optional)
Ex: affinity
Ranking method for order of recommendations. Must be one of "popular", "recent", or "affinity"
GET

Content Segment Recommendation

/api/content/recommend/segment/{segId}?{limit,contentsegment,shuffle,rank}

Response 200

Headers
Content-Type: application/json
Body
  {  
      "data":[  
        {  
          "url":"www.getlytics.com/blog/post/intent_through_content",
          "title":"Understanding User Intent Through Content",
          "description":"Customer Intent comes from understanding the connection between engagement and its contexts. Content modeling and affinity graphs makes interpretation of intent a lot easier. Learn how marketers can benefit from this.",
          "topics":[  
            "customer data platform",
            "data science",
            "content marketing",
            "personalization"
          ],
          "topic_relevances":{  
            "content marketing":1,
            "customer data platform":1,
            "data science":1,
            "personalization":1
          },
          "primary_image":"https://www.getlytics.com/img/blog/posts/intent_through_content/intent_through_content-bg.gif",
          "author":"",
          "created":"2016-06-08T16:11:45.599594093Z",
          "id":"-3435113786560588929",
          "sitename":"Lytics",
          "stream":"default",
          "path":[  
            "blog",
            "blog/post",
            "blog/post/intent_through_content"
          ],
          "aspects":[  
            "article"
          ],
          "language":"unknown",
          "updated":"2016-06-09T12:49:36.870359765Z",
          "fetched":"2016-06-09T12:49:35.812654441Z",
          "meta":[  
            "og:locale/en_us",
            "og:site_name/lytics",
            "og:title/understanding user intent through content",
            "og:type/article",
            "og:url/https://www.getlytics.com/blog/post/intent_through_content"
          ],
          "confidence":0.5916079783099615,
          "visited":true
        }
      ],
      "message":"success",
      "status":200
    }

Content Taxonomy

/api/content/taxonomy{?limit,budget,iter,raw,rawThreshold,cliques,cliqueThreshold}

Get the relationships among topics. This gives the number of documents (content items) having each topic.

There are two methods for generating topic relationships from the content taxonomy through Monte Carlo simulation and through direct calculation from its Bayesian network. The generation method defaults to simulation.

Parameters
limitinteger (optional)
Ex: 150
number of topics to include in the topic graph, capped at 500 topics
budgetfloat (optional)
Ex: 1.0
the depth at which any Monte Carlo simulation can traverse through the graph
iterinteger (optional)
Ex: 8
how many Monte Carlo simulations to run for each topic
rawbool (optional)
Ex: false
whether to generate the topic relationships from its Bayesian network
rawThresholdfloat (optional)
Ex: 0.7
when extracting relationships directly from the Bayesian network, the threshold at which to determine ties
cliquesboolean (optional)
Ex: false
whether to return a single graph or an array of disjoint subgraphs
cliqueThresholdfloat (optional)
Ex: 0.0
when returning cliques, the threshold at which to determine if two cliques should be connected
GET

Content Taxonomy

/api/content/taxonomy{?limit,budget,iter,raw,rawThreshold,cliques,cliqueThreshold}

Response 200

Headers
Content-Type: application/json
Body
{
  "data": {
    "n": 438,
    "nodes": [
      {
        "name": "marketing technology",
        "doc_count": 2
      },
      {
        "name": "AdWords",
        "doc_count": 1
      },
      {
        "name": "ad retargeting",
        "doc_count": 4
      },
      {
        "name": "analytics",
        "doc_count": 2
      },
      {
        "name": "customer service",
        "doc_count": 1
      },
      {
        "name": "data visualization",
        "doc_count": 2
      },
      {
        "name": "data-first marketing",
        "doc_count": 157
      },
      {
        "name": "personalization",
        "doc_count": 15
      }
    ],
    "links": [
      {
        "source": 66,
        "target": 54,
        "value": 0.375
      },
      {
        "source": 66,
        "target": 75,
        "value": 0.25
      },
      {
        "source": 66,
        "target": 37,
        "value": 0.25
      }
    ]
  },
  "message": "success",
  "status": 200
}

Content Corpus

/api/content/corpus?{url,text,topics}

Update the corpus, or collection of content documents, that powers the Content Affinity Engine.

In most cases, content is either scraped when the Content Affinity Engine is turned on, or observed as users engage with content from their activity streams. The corpus API provides methods for modifying the corpus adding custom topics to documents, adding documents for URLs that are private, unlisted, or otherwise irretrievable, etc.

Parameters
urlstring (optional)
Ex: http://www.somedomain.com/blog/great-post
the URL for identifying and retrieving content
textstring (optional)
Ex: here is some body text
the body of the content to be added
topics[]string (optional)
Ex: Data,Hockey
custom topics to append to the document, in addition to topics that will be added with enrichment
POST

Content Corpus

/api/content/corpus?{url,text,topics}

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 '.'

Response 200

Headers
Content-Type: application/json
Body
{
    "status": 200,
    "message": "success",
    "data": {
      "body": [
        "here is some body text"
      ],
      "source": [
        "upload"
      ],
      "updated": [
        "2016-09-13 21:59:38.551972802 -0400 EDT"
      ],
      "url": [
        "http://www.google.com/"
      ],
      "version": [
        "4"
      ]
    }  
}

Topic Curation

/api/content/doc/{docField}/{docId}/topic/{topicLabel}{?relevance}

Add a new topic mid to a content document

Parameters
docFieldstring (required)
Ex: hashedurl
name of field to look up content by
docIdstring (required)
Ex: 123abc
value of field to look up content by
topicLabelstring (required)
Ex: cats
name of topic to add
relevancefloat (optional)
Ex: 0.5
Default: 0.5
the relevance threshold to set for the new topic
POST

Topic Add

/api/content/doc/{docField}/{docId}/topic/{topicLabel}{?relevance}

Add a topic to a Document.

Response 200

Headers
Content-Type: application/json
Body
{
    "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"
    }
}
DELETE

Topic Remove

/api/content/doc/{docField}/{docId}/topic/{topicLabel}{?relevance}

Response 204