Documentation / Developer / Lytics APIs

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

Get a list of topics in the content graph. Topics are updated every 24 hours.

GET

Content Topics

/api/content/topic

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

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": {
         "label": "Customer Data Platform",
         "doc_count": 313,
         "total": 380260,
         "missing": 216043,
         "present": 159628,
         "avg": 0.9704200631406573,
         "tags": [
           "custom"
         ]
    }
}

Content Topic Blocklist

/api/content/topicblocklist

Get a list of the blocklisted topics. Blocklisted topics will have the blocklisted identifier in the tags field.

GET

Content Topic Blocklist Fetch

/api/content/topicblocklist

Fetch the blocklisted 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": [
          "blocklisted"
        ]
      },
      {
        "label": "User Data Unification",
        "doc_count": 273,
        "total": 380636,
        "missing": 216048,
        "present": 154068,
        "avg": 0.6036863622558337,
        "tags": [
          "blocklisted"
        ]
      }
    ]
  }
POST

Content Topic Blocklist Create

/api/content/topicblocklist

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

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": [
          "blocklisted"
        ]
      },
      {
        "label": "User Data Unification",
        "doc_count": 273,
        "total": 380636,
        "missing": 216048,
        "present": 154068,
        "avg": 0.6036863622558337,
        "tags": [
          "blocklisted"
        ]
      }
    ]
  }
PUT

Content Topic Blocklist Update

/api/content/topicblocklist

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

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": [
          "blocklisted"
        ]
      },
      {
        "label": "User Data Unification",
        "doc_count": 273,
        "total": 380636,
        "missing": 216048,
        "present": 154068,
        "avg": 0.6036863622558337,
        "tags": [
          "blocklisted"
        ]
      }
    ]
  }

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.
affinitiesAn object containing each Affinity 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":{
    "url":"https://www.getlytics.com/blog/post/improving_google_analytics?utm_source=linkedin",
    "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",
    "httpstatus":0,
    "humanLanguage":"en",
    "meta":[
        "og:title=stop pretending your insights are actionable: part 1, google analytics",
    ],
    "primary_image":"https://www.getlytics.com/img/blog/defaults/developers.gif",
    "published":"2015-10-23T00:00:00Z",
    "author":"Mark Hayden",
    "sitename":"Lytics",
    "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"
    }
  },
  "message":"success",
  "status":200
}

Content Recommendation

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

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
topicfilter[]string (optional)
Ex: ["Poltics", "Oregon"]
if supplied, only documents that contain all of the topics defined in the `topicfilter` will be returned
rankstring (optional)
Ex: affinity
Ranking method for order of recommendations. Must be either "affinity" or "recent"
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,contentsegment,shuffle,visited,topics,rank,wait,email,url,topicfilter}

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,contentsegment,shuffle,visited,topics,rank,wait,email,url,topicfilter}

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
topicfilter[]string (optional)
Ex: ["Poltics", "Oregon"]
if supplied, only documents that contain all of the topics defined in the `topicfilter` will be returned
rankstring (optional)
Ex: affinity
Ranking method for order of recommendations. Must be either "affinity" or "recent"
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,contentsegment,shuffle,visited,topics,rank,wait,email,url,topicfilter}

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
}

Generic Content Recommendation

/api/content/recommend?{limit,contentsegment,shuffle,visited,topics,rank,wait,email,url,topicfilter}

While the User Recommendation API endpoint surfaces content-recommendations based on a user's topic-affinity, the Generic Content Recommendation API is meant to be used to retrieve recommendations based on a URL or a list of topics.

# get generic content-recommendations
curl -s -H "Authorization: $LIOKEY" \
  -XGET "https://api.lytics.io/api/content/recommend" | jq '.'

# get generic content-recommendations for a content-collection 
curl -s -H "Authorization: $LIOKEY" \
  -XGET "https://api.lytics.io/api/content/recommend?contentsegment=blog_posts" | jq '.'

# get content-recommendations for a certain URL
curl -s -H "Authorization: $LIOKEY" \
  -XGET "https://api.lytics.io/api/content/recommend?url=www.lytics.com" | jq '.'

# get content-recommendations for a list of topics 
curl -s -H "Authorization: $LIOKEY" \
  -XGET "https://api.lytics.io/api/content/recommend?topics=Marketing,Data,Portland" | jq '.'
Parameters
accountstring (required)
Ex: 123
the account ID
contentsegmentstring (optional)
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
topics[]string (optional)
Ex: ["Marketing", "Analytics"]
if supplied, only allow recommendations on content with the specified topics
topicfilter[]string (optional)
Ex: ["Poltics", "Oregon"]
if supplied, only documents that contain all of the topics defined in the `topicfilter` will be returned
rankstring (optional)
Ex: affinity
Ranking method for order of recommendations. Must be either "affinity" or "recent"
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

Generic Content Recommendation

/api/content/recommend?{limit,contentsegment,shuffle,visited,topics,rank,wait,email,url,topicfilter}

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.

The Content Taxonomy is updated weekly.

Parameters
limitinteger (optional)
Ex: 150
number of topics to include in the topic graph, capped at 500 topics
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 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
        }
     }
}

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

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
        },
        "affinities": {
            "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}

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

Response 204

Affinity Config

/api/content/config/{id}

An Affinity Config defines the relationship between the user table and an inventory table and enables the creation of Affinities on user profiles.

The Affinity Config object has the following attributes:

fieldDataTypeDescription
idstringUnique ID assigned by Lytics
createdDateCreated date of the Affinity Config
updatedDateLast-Updated date of the Affinity Config
invalidbooleanIndicates whether an Affinity Config is invalid
authorstringThe author of the Affinity Config
labelstringLabel of the Affinity Config
descriptionstringDescription of the Affinity Config
lhs_tablestringLeft-hand-side table (ie user)
lhs_node_idstringLeft-hand-side Node ID is the name of the user-history field
lhs_output_idstringLeft-hand-side Output ID is the name of the field where affinities are written
rhs_tablestringRight-hand-side table (ie content, product)
rhs_node_idstringRight-hand-side Node ID is the name of the unique identifier for entities belonging to the Right-hand-side table
rhs_feature_idstringRight-hand-side Feature ID is the name of the field that captures 'features' for entities belonging to the Right-hand-side table
explicit_affinitiesbooleanCalculate explicit affinities by not traversing the feature-graph
inferred_affinitiesbooleanOnly evaluate inferred affintiies
blocklisted_topics[]stringFeatures to ignore
Parameters
idstring (required)
Ex: 123abc
id of **Affinity Config**
GET

Affinity Config Fetch

/api/content/config/{id}

Fetch an Affinity Config by id

Response 200

Headers

Content-Type: application/json

Body

{
    "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"
    }
}
POST

Affinity Config Create

/api/content/config/{id}

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

Response 201

Headers

Content-Type: application/json

Body

{
    "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"
    }
}
PUT

Affinity Config Edit

/api/content/config/{id}

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

Response 201

Headers

Content-Type: application/json

Body

{
    "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

Affinity Config Delete

/api/content/config/{id}

Delete an Affinity Config

Response 204

Affinity

/api/content/affinity/{id}

An Affinity is a group of similar topics describing user's interests. Affinities are used for audience generation.

The Affinity object has the following attributes:

fieldDataTypeDescription
idstringUnique ID assigned by Lytics
config_idstringAffinity Config associated with the Affinity
createdDateCreated date of the Affinity
updatedDateLast-Updated date of the Affinity
author_idstringThe author of the Affinity
labelstringLabel of the Affinity
descriptionstringDescription of the Affinity
slugstringSlug version of the label for the Affinity
topics[]stringTopics included in the Affinity
methodstringMethod of the Affinity
Parameters
idstring (required)
Ex: 123abc
id of the Affinity
configstring (optional)
Ex: 456def
Affinity Config asociated with the Affinity
sideloadstring (optional)
Ex: works,segments
additional objects to sideload as a command delimited string
GET

Affinity Fetch

/api/content/affinity/{id}

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

Response 200

Headers

Content-Type: application/json

Body

{
    "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"
    }
}
POST

Affinity Create

/api/content/affinity/{id}

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

Response 201

Headers

Content-Type: application/json

Body

{
    "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"
    }
}
PUT

Affinity Edit

/api/content/affinity/{id}

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

Response 201

Body

{
    "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

Affinity Delete

/api/content/affinity/{id}

Delete an Affinity

Response 204