RESPONSE TYPES

The API returns a JSON document made up of several JSON objects defined in the following tables. The Required column denotes which fields are always present and which fields are optional based on the data being returned. URLs, where used, always include the protocol (http or https).

Top level response

Field	Description	Required
data	The actual data results. Either a Media Page Data object or a single Media Item object.	Yes
metadata	Object with trace identifiers and diagnostic info.	Yes
error	Object with any error info.	No
paging	Object with cursors and prev/next links if applicable.	No

Media Page Data

Field	Description	Required
items	List of 0 to N media item results.	Yes
totalCount	Number of total results available in the query. Use the "after" paging cursor to fetch more results.	Yes

Media Item

Field	Description	Required
id	Uniquely identifies a media item. These are stable across requests and can be used in the GET Media Item API.	Yes
source	Source object that describes where the content originated.	Yes
labels	List of 0 or more strings that represent user-defined labels added in the Social Commerce App.	Yes
media	Media object that gives the type and links to the underlying media.	No
products	List of 0 or more Product objects.	Yes

Media Item Source

Field	Description	Required
type	The social network where the content was originally posted: pinterest, facebook, instagram, twitter, tumblr. If the content did not come from a social network, it will not have info like user, link, caption, etc.	Yes
postedTimestamp	Epoch timestamp (seconds) when the content was originally posted to the social network.	Yes
user	User object describing details of the content post author.	No
user.username	User's username.	No
user.link	User's profile link.	No
user.image	User's profile avatar with the original, small, medium, and square image variations.	No
user.followerCount	User's follower count.	No
user.followingCount	User's following count.	No
link	Link to the post on the social network.	No
caption	String caption.	No
commentCount	Approximate number of comments the original post received on the social network.	No
likeCount	Approximate number of likes the original post received on the social network.	No

Media Item Media

Field	Description	Required
type	String enumeration: photo, gif, video.	Yes
original	The original media contents.	Yes
small, medium, large, extraLarge	Various sizes of the image. Not provided for gif media types.	No
smallSquare, mediumSquare, largeSquare, extraLargeSquare	Various square smart cropped sizes of the image. Not provided for gif media types. Smart cropping looks at the features and spatially tagged products to produce an optimal crop. More info in this blog post.	Yes

Media Item Product

Field	Description	Required
id	Uniquely identifies a product in the Social Commerce platform. It does not have meaning within the brand's product catalog.	Yes
name	Name or Title of the product	Yes
images	List of 1 or more images for the product. Each image has different size and square smart cropped variations.	Yes
link	Link to the product page or other destination URL.	Yes
price.display	Display price (value and currency) of the product. This comes directly from the brand's product feed.	No
metadata	JSON object (key/value pairs) of various product metadata (e.g. productId, category, brand, manufacturer, sale_price, color, etc.).	No
spatialTag	JSON object with x, y, and label fields describing the spatial tag. x and y are floating point numbers defining the percent location of the tag on the original (or resized) media from the top/left corner.	No