This page defines the common data types that are used in the API
Holds data related to a topic
- id
- long - topic id
- smallImageUrl
- string - topic image url (16x16)
- mediumImageUrl
- string - topic image url (48x48)
- imageUrl
- string - topic image url (96x96)
- largeImageUrl
- string - topic image url (192x192)
- backgroundImage *
- string - URL of the topic's background image, if set
- backgroundRepeat *
- string - CSS background-repeat property to be applied to the topic's background image
- backgroundColor *
- string - topic's background color expressed as a six character hexa code (eg. FFCC00)
- description
- string - topic description
- name
- string - topic name
- shortName
- string - topic short name (used in website urls)
- url
- string - topic url
- lang
- string - the language of the topic
- isCurator
- boolean - true if topic is curated by current user
- isFollowing
- boolean - true if topic is following by current user
- isPrivate
- boolean - true if topic is private
- curablePostCount *
- int - number of curable posts in this topic
- curatedPostCount
- int - number of curated posts in this topic
- unreadPostCount *
- int - number of unread posts
- score
- int - the score of the topic
- creator
- user - creator of the topic
- pinnedPost *
- post - post pinned at the top of the topic
- curablePosts *
- post[] - an array of posts to curate on this topic
- curatedPosts *
- post[] - an array of curated posts on this topic
- tags
- topic_tag[] - an array of tags present on this topic
- stats
- topic_stats - the stats for this topic
- sharers *
- sharer[] - the list of sharers of the user
- scheduledPosts *
- post[] - the list of scheduled posts
* optional fields: depending on where and how the topic is returned
Holds data related to a tag of a topic
- tag
- string - the tag
- postCount
- int - the number of posts in the topic tagged with this tag
Holds data related to a post
- id
- long - the id of the post
- content
- string - post content in plain text
- htmlContent
- string - post content in HTML
- displayImageInsteadOfHtmlFragment
- string - an image is displayed in the topic instead of the htmlFragment
- htmlFragment
- boolean - additional embedded HTML content if applicable (eg: embedded videos)
- insight
- string - the insight of the curator
- htmlInsight
- string - the html version of the insight
- title
- string - the post title
- thanksCount
- int - the number of times this post was thanked
- reactionsCount
- int - the number reactions on this post
- source
- source - the source of the post
- twitterAuthor
- string - if source is a twitter search, the twitter user who wrote the original tweet
- url
- string - original url of the post
- scoopUrl
- string - url of the post on the scoop platform
- scoopShortUrl
- string - shortened url of the post on the scoop platform
- smallImageUrl
- string - url of the image chosen by the curator, referred below as "post image" (max width: 100px)
- mediumImageUrl
- string - url of the image chosen by the curator, referred below as "post image" (max width: 200px)
- imageUrl
- string - url of the image chosen by the curator, referred below as "post image" (max width: 400px)
- largeImageUrl
- string - url of the image chosen by the curator, referred below as "post image" (max width: 1024px)
- imageWidth
- int - width in pixel of the original post image
- imageHeight
- int - height in pixel of the original post image
- imageSize
- int - size of the post image in the topic view
- imagePosition
- string - position of the post image in the topic view: "left" | "center" | "right"
- imageUrls
- string[] - array of urls of image selector in curation mode
- tags
- topic_tag[] - array of tags
- commentsCount
- int - the number of comments for this post
- isUserSuggestion
- boolean - true if the post is a user suggestion
- suggestedBy
- user - the user that suggested this post (not present if the post is not a user suggestion)
- pageViews
- long - number of time this post has been viewed
- pageClicks
- long - number of time this post has been clicked
- edited
- boolean - true if the description of this post has been manually edited by the curator
- author
- user - the author of the post
- publicationDate
- timestamp - the publication date of the original article
- curationDate
- timestamp - the curation date of the post (aka the publication date on Scoop.it)
- comments
- post_comment[] - the list of comments
- thanked *
- boolean - true if the user has already thanked this post
- topicId
- long - the id of the topic this post is belonging to
- topic **
- topic - the topic this post is belonging to
- scheduledDate **
- timestamp - the scheduled date of the article
- metadata
- map<string,string> - metadata about this post
* only present in authenticated mode
Holds data related to a comment. A comment is a typed reaction to a post.
Comment type
- text
- A simple text comment. The text field will hold the text typed by the user
- share
- The post has been shared. The sharerId will hold the id of the sharer used to share the post (typically: twitter, facebook, linkedin...)
- thank
- The post has been thanked
- rescoop
- The post has been rescooped to another topic. The rescoopedPostId holds the id of the rescooped post
- type
- enum - the type a the comment one of "text", "share", "thank", "rescoop" (see above)
- text
- string - the comment text if applicable
- sharerId
- string - the sharer id if applicable
- rescoopedPostId
- long - id of the rescooped post if applicable
- date
- timestamp - the comment date
- author
- user - the comment author
Holds data related to a Source: something that suggests content to curate to users.
- id
- long - id of the source
- name
- string - name of the source (human readable)
- description
- string - description of the source (human readable)
- type
- string - type of the source (developper readable identifier)
- iconUrl
- string - url of an icon representing this source
- url
- string - url of this source (may be a user profile url, a link to a youtube search...)
- rssUrl
- string - url of the rss feed (only present if type==rss)
- twitterUser
- string - twitter user (only present if type==twitter_follow_user)
- twitterSearchQuery
- string - search query (only present if type==twitter_search)
- twitterListName
- string - list name (only present if type==twitter_list)
- twitterListOwner
- string - list owner name (only present if type==twitter_list)
- webpageUrl
- string - webpage url (only present if type==webpage)
- query
- string - advanced search query (only present if type==advanced_search)
Holds data related to a user
- id
- long - user id
- name
- string - user name
- shortName
- string - user shortName (used in website urls)
- url
- string - user profile url
- bio
- string - user bio
- smallAvatarUrl
- string - user avatar url (16x16)
- mediumAvatarUrl
- string - user avatar url (48x48)
- avatarUrl
- string - user avatar url (96x96)
- largeAvatarUrl
- string - user avatar url (192x192)
- sharers *
- sharer[] - the list of sharers of the user
- curatedTopics
- topic[] - the list of topic this user is the curator
- followedTopics
- topic[] - the list of topics followed by this user
- premium-features *
- premium-features[] - the list of premium-features of the user (for now possible values are directLink and scheduling)
* only present on
/profile request if the requested user is the current user.
Holds data related to a "sharer". A "sharer" is basically an account to a publish service the user registered in the dedicated website page(eg: twitter account, facebook account, tumblr account).
- sharerName
- string - display name of this sharer
- sharerId
- string - internal id
- cnxId
- long - internal id
- name
- string - the name of the user on the external service represented by this sharer, for a facebook account it will be the facebook user name
- profileImage
- string - optional, the url of the profile image of the user on this sharer (for Facebook, the profile picture)
- sharerImage
- string - the url of the image of the sharer, ie. the logo
- shareAsImageEnable
- boolean - true, if the share as image feature is enable for the pair sharer / user
- shareAsImageDefaultValue
- string - the last value
- mustSpecifyShareText
- - true if the external service needs a manually specified text to publish a post
Holds data related to a notification.
For each notification type a bunch of fields is returned in the notification object.
This section is currently not documented. You are free to discover different kind of notifications.
We will not remove any field from a notification object. So it can be considered as stable.
Enum describing the type of a <
notification >. New values may be added at any time: don't be too strict in your code, just ignore notifications having a value you do not support.
- topicNewComment
- a comment has been added on a topic
- topicSubscription
- a new user subscribed to a topic curated by the current user
- userPostThanked
- a post has been thanked on a topic curated by the current user
- userWelcomeMessage
- the welcome message notification
- userSnsContact
- a friend or someone followed by the current user has joined or is using Scoop.it
- userSnsTopicCreated
- a friend or someone followed by the current user created a topic
- userSuggestionAccepted
- a suggestion of the current user has been accepted
- userNewCommentResponse
- a comment has been posted on a post the current user has commented
- userNewUserSuggestion
- a user suggestion has been accepted on a topic the current user is following
- topicCuratorNewUserSuggestion
- a new user suggestion has been added on a topic curated by the current user
- pendingUserSuggestionReminder
- there is pending user suggestion on a topic curated by the current user
Holds statistics related to a topic
- uv
- int - visitors
- uvp
- int - visitors progression
- v
- int - views
- vp
- int - views progression
- updated
- timestamp - last update timestamp
- createdDate
- timestamp - creation timestamp
- creatorName
- string - creator name
- creatorId
- long - creator id
- followers
- int - number of followers of this topic
A long (64 bit) integer counting the number of milliseconds since the Unix epoch (since midnight Coordinated Universal Time (UTC) of January 1, 1970, not counting leap seconds).
All server responses are returning the current server timestamp. (currentTime field)
Holds data related to an interest
- id
- long - interest id
- name
- string - interest name
- shortName
- string - interest short name (used in website urls)
- lang
- string - interest language
- url
- string - interest url
- topics
- topic[] - the list of topics in the interest
- users
- user[] - the list of users in the interest
- posts
- post[] - the list of posts in the interest
A suggestion engine and its configuration
- id
- long - suggestion engine id
- name
- string - the name of the suggestion engine
- type
- string - "topic", "research_content" or "content_monitoring".
- sorter
- string - the sorter used: "relevance", "freshness" or "popularity"
- maxSuggestionAge
- int - the maximum number of days for the age of a suggestion. -1 for no maximum
- keywords
- string[] - the list of configured keywords
- includedDomains
- string[] - the list of url domains to include
- excludedDomains
- string[] - the list of url domains to exclude
- containsAllKeyword
- string[] - the list of keywords which all must match the suggestions
- containsAnyKeyword
- string[] - the list of keywords which any should match the suggestions
- doesNotContainKeywords
- string[] - the list of keywords which must not match the suggestions
- saved_searches
- saved_search[] - the list of saved searches in this suggestion engine
A suggestion engine saved search
- id
- long - search id
- name
- string - the name of the saved search
A suggestion
- id
- string - suggestion id
- url
- string - the url of the suggestion
- date
- long - the date of the suggestion, in milliseconds since epoch
- title
- string - the title of the suggestion
- highlightedTitle
- string - the title with matched keywords surrounded by html tags
- description
- string optional - the description of the article, if any
- htmlDescription
- string optional - the description of the article with html tags
- content
- string optional - the full content of the suggestion, if any
- htmlContent
- string optional - the full content of the suggestion with html tags
- highlightedContent
- string - the content (or the description as fallback) of the suggestion with matched keywords surrounded by html tags
- ogImageUrl
- string optional - the og:image url, if any
- websiteIcon
- string optional - the url of the icon of the website hosting the url of the suggestion
- matchingKeywords
- string[] - the list of matched keywords
- category
- string - the category: "Articles", "Documents", "Pictures", "Videos" or "SocialNetworks"
- imageUrls
- string[] - the list of url of the images found in the suggestion
A list of recipients. Newsletters can be send to a recpipients list using our Campaign tool.
- id
- long - recipients list id
- name
- string - the name of the recipients list
- emails
- string[] - the list of emails subscribed to the recipients list (note that this list may contain unsubscribed recipients)