NAV
cURL ruby

Introduction

Welcome to the backstitch API! You can use our API to build and access backstitch topic pages to leverage our content curation engine for your app.

Information regarding limits and pricing can be found here.

Authentication

require 'rest_client'

# Modification requires both an organization's key and a topic's token
response = RestClient.post 'https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/sources', :params => {:key => '70b5aa707ca6013231ce482a14180728', :data => [{:service => 'twitter_user', :value => 'backstitch'}]}

# Read-Only request only requires a topic's token
response = RestClient.get 'https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728'
# Modification requires both an organization's key and a topic's token
curl https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/sources \
  -H "Content-Type: application/json" \
  -d '{"key": "70b5aa707ca6013231ce482a14180728", "data": [{"service": "twitter_user", "value": "backstitch"}]}'

# Read-Only request only requires a topic's token
curl https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728

Make sure to replace 70b5aa707ca6013231ce482a14180728 with your organization’s key and 9b5d30a07d4001325ede482a14180728 with your topic’s token.

backstitch uses API keys and tokens to allow access to the API. For all actions that create or modify topic pages the organization’s key must be passed. For reading results from a topic page only the topic’s token is required.

Action Organization Key Topic Token
CREATE X X*
READ X
UPDATE X X
DELETE X X

Widget

The backstitch widget allows you to easily embed content on your blog or website. Using our lightweight widget, your topic’s results can be displayed responsively anywhere that JavaScript is embeddable.

Since the widget is responsive it will fit to the width of its container (and will expand from one column to two or three).

Using the Widget

To use simply paste the following code wherever your want your widget to appear.

<script async type="text/javascript" src="https://api.backstit.ch/v1/topic/widget.js?count=10&token={TOPIC_TOKEN}&ref=encodeURIComponent(window.location.href)"></script>

If you prefer to place the script tag in your page’s HEAD section or if you are building the widget dynamically and appending to the DOM using Javscript reference the container_id parameter in the table below.

Opening Results

Clicking on a result by default will open the link in a new window or tab (depending on your browser). Passing the “open_in_widget=true” parameter will cause results to open in a pop-up modal, never taking the user off your page where the widget is embedded.

To close this modal once opened, the user can either press the escape key, click off the modal, or click the “X” in the upper-right corner of the modal.

This modal can also be custom-styled by passing the “content_theme=none” parameter.

Widget URL Parameters

Parameter Required Description
token Yes The topic’s api token.
count Yes How many topic results to desplay.
ref Yes The url of the page loading the widget. This is used so backstitch can provide you metrics on user engagement.
container_id No The id of the container to load the widget. If not provided the widget will render wherever you place the bootstrap script.
on_click No A JavaScript method name that will be called when a result is clicked from the widget on your page. Method will be passed the result URL, result reference ID, result type, and a boolean telling whether the result has been scraped or not (in that order).
open_in_widget No Passing true will open results from the widget in a content viewer on the page rather than opening a new window.
suppress_duplicates No Passing true will attempt to suppress any duplicate results that might be displayed on the widget.
card_theme=‘none’ No Disables loading of the default style for the result cards, letting you supply your own.
content_theme=“none” No Disables loading of the default stype for the content viewer, letting you supply your own.
theme=“none” No Disables loading of the default style for both the cards and the content viewer, letting you supply your own.

Styling the Widget

By default the widget loads a responsive card layout similar to the native interface found on the backstitch web app.

If you want to override this with your own styles you can either:

Source-Specific Styling

Each result in the widget also has an extra class at its root that denotes where it originally came from.

While the default theme doesn’t provide any style rules for these they are available if you wanted to style results different based on source.

Root Classes
backstitch-twitter-result
backstitch-facebook-result
backstitch-instagram-result
backstitch-youtube-result
backstitch-linkedin-result
backstitch-news-result

API 2.0 Endpoints

The backstitch API 2.0 includes the ability to build and manage topic pages from a RESTful interface along with a more consistent endpoint schema for working with topics.

All API 2.0 requests use the base url of https://api.backstit.ch/v2 and most authenticate by passing the topic’s token as a url parameter and the organization’s key as a query parameter.

Get Organization Details

require 'rest_client'

response = RestClient.get 'https://api.backstit.ch/v2/organizations/70b5aa707ca6013231ce482a14180728.json'
curl https://api.backstit.ch/v2/organizations/70b5aa707ca6013231ce482a14180728

The above command returns JSON structured like this:

{
  "id": 1049,
  "name": "Awesome Rocket Inc.",
  "logo": {
    "url": "http://backstitch-user-uploads.s3.amazonaws.com/production/organization_logos/awesome_rocket_logo.png",
    "width": 181,
    "height": 36
  },
  "highlight_color": "#1ba5ca",
  "key": "70b5aa707ca6013231ce482a14180728"
}

This endpoint retrieves basic details about an organization.

HTTP Request

GET https://api.backstit.ch/v2/organizations/{ORGANIZATION_KEY}

URL Parameters

Parameter Required Description
ORGANIZATION_KEY yes Your organization’s api key is obtained from the organization dashboard under settings.

Returns

Field Data Type Description
id integer A unique identifier for the organization.
name string The name given to the organization.
logo object An optional logo uploaded for the organization.
highlight_color string An optional theme color set for the organization.
key string The organizations’s api key.

Get Organization Teams

require 'rest_client'

response = RestClient.get 'https://api.backstit.ch/v2/organizations/70b5aa707ca6013231ce482a14180728/teams.json'
curl https://api.backstit.ch/v2/organizations/70b5aa707ca6013231ce482a14180728/teams

The above command returns JSON structured like this:

[
    {
        "id": 118,
        "name": "Awesome Rocket (all)",
        "member_count": 5,
        "team_members": [
            {
                "id": 129,
                "is_verified": false,
                "display_name": "John Doe",
                "email": "test5@backstit.ch",
                "last_login_at": "2015-01-06T20:09:19.793Z"
            },
            {
                "id": 132,
                "is_verified": true,
                "display_name": "Jane Doe",
                "email": "test2@backstit.ch",
                "last_login_at": "2014-11-28T19:54:57.977Z"
            },
            {
                "id": 133,
                "is_verified": true,
                "display_name": "Jess Smith",
                "email": "test@backstit.ch",
                "last_login_at": "2014-11-28T18:37:08.242Z"
            },
            {
                "id": 134,
                "is_verified": true,
                "display_name": "Jordan Warzecha",
                "email": "test3@backstit.ch",
                "last_login_at": null
            },
            {
                "id": 138,
                "is_verified": true,
                "display_name": "Tommy Bonderenka",
                "email": "test4@backstit.ch",
                "last_login_at": "2014-12-30T16:16:58.501Z"
            }
        ]
    },
    {
        "id": 119,
        "name": "Research & Development",
        "member_count": 1,
        "team_members": [
            {
                "id": 130,
                "is_verified": false,
                "display_name": "John Doe",
                "email": "test5@backstit.ch",
                "last_login_at": "2015-01-06T20:09:19.793Z"
            }
        ]
    }
]

This endpoint retrieves basic details about every team in an organization, including member information.

HTTP Request

GET https://api.backstit.ch/v2/organizations/{ORGANIZATION_KEY}/teams

URL Parameters

Parameter Required Description
ORGANIZATION_KEY yes Your organization’s api key is obtained from the organization dashboard under settings.

Query Parameters

Parameter Required Description
team no If provided, will only return teams that have names that match the provided name.

Returns

Field Data Type Description
id integer A unique identifier for the team.
name string The name given to the team.
member_count integer The total number of team_members associated with the team.
team_members array Details on each team_member associated with the team.

Get Organization Topics

require 'rest_client'

response = RestClient.get 'https://api.backstit.ch/v2/organizations/70b5aa707ca6013231ce482a14180728/topics.json'
curl https://api.backstit.ch/v2/organizations/70b5aa707ca6013231ce482a14180728/topics

The above command returns JSON structured like this:

[
  {
    "id": 10482,
    "name": "Apple News",
    "description": "The latest news around Apple",
    "banner": {
      "url": "http://backstitch-user-uploads.s3.amazonaws.com/production/topic_banners/18155_1421233959.jpg",
      "width": 912,
      "height": 384
    },
    "token": "700cc690776001326156482a14180728",
    "filters": [
      {
        "id": 20101,
        "value": "Apple",
        "type": "include"
      }
    ],
    "sources":[
      {
        "id": 782,
        "name": "MacRumors",
        "icon": {
          "url": "http://images-backstitch.s3.amazonaws.com/next/service_catalog/macrumors_icon.png",
          "width": "16",
          "height": "16"
        },
        "banner": {
          "url": "http://images-backstitch.s3.amazonaws.com/next/service_catalog/macrumors_banner.jpg",
          "width": "650",
          "height": "240"
        },
        "params": {
          "feed_url": {
            "type": "url",
            "value": "http://feeds.macrumors.com/MacRumors-All"
          }
        },
        "filters": [],
        "service": "rss"
      },
      {
        "id": 345,
        "name": "Technology news - CNNMoney.com",
        "icon":{
          "url": "http://cnn.com/favicon.ie9.ico",
          "width": 32,
          "height": 32
        },
        "banner":{
          "url": "http://i2.cdn.turner.com/money/dam/assets/150113142501-3doodler-thumbnail-620x348.jpg",
          "width": null,
          "height": null
        },
        "params":{
          "feed_url":{
            "type": "url",
            "value": "http://rss.cnn.com/rss/money_technology.rss"
          }
        },
        "filters":[
          {
            "id": 20102,
            "value": "Android",
            "type": "exclude"
          }
        ],
        "service": "rss"
      }
    ]
  }
]

This endpoint retrieves a list of organization owned topics that have the API add-on enabled.

HTTP Request

GET https://api.backstit.ch/v2/organizations/{ORGANIZATION_KEY}/topics

URL Parameters

Parameter Required Description
ORGANIZATION_KEY yes Your organization’s api key is obtained from the organization dashboard under settings.

Returns

Field Data Type Description
id integer A unique identifier for the topic.
name string The name given to the topic.
description string An optional description of the topic.
banner object The topic’s displayed banner image if one was uploaded.
token string The topic’s api token.
filters array A list of global keyword filters set on the topic.
sources array A list of sources included in the topic.

For a more descriptive breakdown of the topic fields reference the Get Topic Details section.

Create Topic

require 'rest_client'

response = RestClient.post 'https://api.backstit.ch/v2/topics.json', {:key => '70b5aa707ca6013231ce482a14180728', :name => 'Local Detroit News', 'sources[]' => [{:service => 'twitter_user', :value => 'backstitch'}]}
curl -X POST https://api.backstit.ch/v2/topics
  -d "key=70b5aa707ca6013231ce482a14180728&name=Local%20Detroit%20News"

The above command returns JSON structured like this:

{
  "id": 23942,
  "name": "Local Detroit News",
  "description": null,
  "banner": null,
  "token": "9b5d30a07d4001325ede482a14180728",
  "sources": [],  
  "filters": [],
  "errors": null
}

Possible error messages:

{
  "message": "A topic name is required."
}
{
  "message": "Invalid organization API Key"
}
{
  "message": "Invalid permission type: everyone"
}
{
  "message": "Invalid filter-type: has",
  "type": "has",
  "phrase": "Detroit"
}
{
  "message": "Invalid service: facebook_page",
  "service": "facebook_page",
  "value": "backstitch"
}
{
  "message": "Invalid topic to clone from"
  "token": "9b5d30a07d4001325ede482a14180728"
}

This endpoint creates a new organization owned topic with the API add-on enabled.

HTTP Request

POST https://api.backstit.ch/v2/topics

Query Parameters

Parameter Required Default Description
key yes Your organization’s api key that is obtained from the organization dashboard under settings.
name yes The name of your topic.
banner no The url of an image to upload as the topic’s banner. Must include http or https and be a png, jpg, or gif.
description no An optional description of the topic.
permission no private Whether or not the topic is publicaly viewable through backstitch. Options are private (only organization members may view the topic) or public (anyone can view the topic including search engines).
team no Organization (all) The name of the team that this topic should belong to.
sources no A list of sources to include in your topic at the time of creation. Detailed Documentation
filters no A list of global filters to set on your topic at the time of creation. Detailed Documentation
topic_tokens no A list of API tokens for the topics to copy sources and filters from. Detailed Documentation

Returns

Field Data Type Description
id integer A unique identifier for the topic.
name string The name given to the topic.
description string An optional description of the topic.
banner object The topic’s displayed banner image if one was uploaded.
token string The topic’s api token.
sources array A list of included sources.
filters array A list of global keyword filters set on the topic.
errors array A list of any errors that occured during topic creation.

Error Messages

Message Description
A topic name is required. A topic name was not provided in the required name parameter.
Invalid organization API key The API key provided in the required key parameter was invalid, or wasn’t provided.
Invalid permission type: permission The permission provided via the permission parameter was invalid (only private or public are supported).
Invalid filter-type: filter-type The filter-type provided is not a backstitch-supported filter-type. Supported types can be found under available filter types in Add Topic Filters.
Invalid service: service The given service was not a supported service. Supported services can be found under available services in Add Topic Sources.
Invalid topic to clone from A token provided to clone from another topic was not found/invalid.

Create Custom Sources

requre 'rest_client'

RestClient.post 'https://api.backstit.ch/v2/organizations/9211967035420133bff950e140978a72/create_source', {:team => 'Research and Development', :name => "Test API Source", :description => "Test Description", :visible_days => 10, :allow_sharing => true}

curl -X POST https://api.backstit.ch/v2/organizations/9211967035420133bff950e140978a72/create_source?team=Researc+and+Development&name=Test+API+Source&description=Test+Description&visible_days=10&allow_sharing=true

This endpoint is for creating new custom sources for the organization.

HTTP Request

POST https://api.backstit.ch/v2/organizations/{ORGANIZATION_KEY}/create_source

URL Parameters

Parameter Required Description
ORGANIZATION_KEY yes Your organization’s api key is obtained from the organization dashboard under settings.

Query Parameters

Parameter Required Default Description
name yes The name of the custom source.
description no An optional description of the source.
promoted_days no 0 The number of days the posts will be promoted to the top of the topic.
allow_sharing no false Passing true will allow posts from this source to be shared publicly.
icon no backstitch logo The url of an image to upload as the source’s icon. Must include http or https and be a png, jpg, or gif.
team no Organization(all) The team that the custom source will belong to.

Add Topic Sources

require 'rest_client'

response = RestClient.post 'https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/sources.json', {:key => '70b5aa707ca6013231ce482a14180728', 'data[]' => [{:service => 'facebook_user', :value => 'backstitchapp', 'filters[]' => [{:type => 'include', :value => 'detroit'}]}]}
curl https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/sources \
  -d 'key=c7f6e1707f090132fe5a50e140978a72&data[][service]=facebook_user&data[][value]=backstitchapp&data[][filters][][type]=include&data[][filters][][phrase]=detroit}]}]}&data[][service]=twitter_user&data[][value]=backstitch'

The above command returns JSON structured like this:

{  
  "errors": [],
  "sources": [
    {
      "id": 76,
      "name": "Facebook Posts from backstitchapp",
      "icon": {
        "url": "http://graph.facebook.com/373050736086342/picture",
        "width": 50,
        "height": 50
      },
      "banner": {
        "url": "http://images-backstitch.s3.amazonaws.com/next/service_catalog/facebook_banner.jpg",
        "width": 650,
        "height": 240
      },
      "value": "backstitchapp",
      "filters": [
        {
          "id": 13414,
          "value": "detroit",
          "type": "include"
        }
      ],
      "service": "facebook_user"
    }
  ]
}

Possible error messages:

{
  "message": "Invalid topic"
}
{
  "message": "Source already added",
  "service": "facebook_hashtag",
  "value": "detroit"
}
{
  "message": "Service not authorized: instagram_user",
  "service": "instagram_user",
  "value": "backstitch"
}
{
  "message": "Invalid service: facebook_tag",
  "service": "facebook_tag",
  "value": "detroit"
}

This endpoint is for including new sources into the topic.

HTTP Request

POST https://api.backstit.ch/v2/topics/{TOPIC_TOKEN}/sources

URL Parameters

Parameter Required Description
TOPIC_TOKEN yes The topic’s token generated from adding the API add-on from the topic editor or returned by the Create Topic endpoint.

Query Parameters

Parameter Required Default Description
key yes Your organization’s api key is obtained from the organization dashboard under settings.
data yes An array of new sources to add to your topic.
crawl_url no This will crawl the specified url and add any sources found on the website. This includes available RSS feeds and listed social media accounts. Example: http://www.cnn.com (Must contain http:// prefix)

Data Child Parameters

Parameter Required Default Description
service yes The name of the new source’s service.
value yes The parameter for the new source as required by the service.
filters no An array of filters to be set on the source. Detailed Documentation

Possible Value Types

Value Type Example
empty null or “”
phrase “Internet of Things”
tag “InternetOfThings”
username “backstitch”
location “Detroit, MI”
url “http://rss.cnn.com/rss/cnn_topstories.rss”
custom source name “internal feed”

Available Services

Requires Linked Account* Service Value Type Description
X app_dot_net_hashtag tag Retrieves public App.net Alpha posts by hashtag.
dealfind_deals nothing Retrieves the latest deals from Dealfind.
backstitch_custom custom source name Adds a backstitch-created custom source.
X facebook_user username Retrieves public Facebook posts made by a user or a company page.
X flickr_group username Retrieves public Flickr photos published to a Flickr group.
X flickr_mention phrase Retrieves public Flickr photos that mentions the phrase in its description.
X google_plus_user username Retrieves public Google+ posts made by a user.
groupon_deals location Retrieves Groupon deals for a location.
X instagram_popular nothing Retrieves the most popular photos currently on Instagram.
X instagram_hashtag phrase Retrieves public Instagram photos by hashtag.
X instagram_user username Retrieves public Instagram photos published by a user.
X instagram_area location Retrieves public Instagram photos posted around a location.
X linkedin_user username Retrieves public LinkedIn posts by a user.
living_social_deals location Retrieves the latest Living Social deals.
subreddit tag Retrieves Reddit submissions made to a public /r subreddit.
rss url Retrieves articles from an RSS feed.
tanga_deals nothing Retrieves the latest deals from Tanga.
tee_fury_deals nothing Retrieves the latest deals from Tee Fury.
X tumblr_tagged tag Retrieves public Tumblr posts by tag.
X twitter_mention phrase Retrieves public Tweets that contain a phrase.
X twitter_hashtag tag Retrieves public Tweets by hashtag.
X twitter_user username Retrieves public Tweets made by a user.
woot_daily_deals nothing Retrieves the latest Woot deals.
woot_plus_deals nothing Retrieves the latest Woot Plus deals.
X youtube_user username Retrieves public videos posted by a YouTube user or account.

*These services require an associated account to be linked from the organization dashboard.

Returns

Field Data Type Description
errors array A list of errors for sources that were unable to be included for some reason.
sources array A list of sources that were successfully added to the topic.

Error Messages

Message Description
Invalid topic The topic token provided was not valid.
Source already added The topic already contains the returned source.
Service not authorized: service The service for the provided source has not been authenticated through the backstitch admin portal.
Invalid service: service The service provided is not a valid service. Refer to the Available Services above for reference.

Add Topic Filters

require 'rest_client'

response = RestClient.post "https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/filters.json", {:key => "70b5aa707ca6013231ce482a14180728", 'data[]' => [{:type => "include", :phrase => "Captain America"}]}
curl https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/filters \
  -d 'key=c7f6e1707f090132fe5a50e140978a72&data[][type]=include&data[][phrase]=Captain%20America'

The above command returns JSON structured like this:

{
  "errors":[],
  "filters":[
    {
      "id": 3242,
      "phrase": "Captain America",
      "type": "include"
    }
  ]
}

Possible error messages:

{
  "message": "Invalid topic"
}
{
  "message": "Invalid filter-type: must-have",
  "type": "must-have",
  "phrase": "detroit"
}
{
  "message": "Filter already added.",
  "phrase": "detroit",
  "type": "include"
}

This endpoint sets a new global filter on the topic. All filters are chained using an OR expression and are evaluated based on variations of the phrase’s contents. (example: restaurant also matches restaurants)

Filters are applied to all Result Type fields and can be used for full-text searching of content or for even matching specific usernames in the orgin or source objects.

HTTP Request

POST https://api.backstit.ch/v2/topics/{TOPIC_TOKEN}/filters

URL Parameters

Parameter Required Description
TOPIC_TOKEN yes The topic’s token generated from adding the API add-on from the topic editor or returned by the Create Topic endpoint.

Query Parameters

Parameter Required Default Description
key yes Your organization’s api key is obtained from the organization dashboard under settings.
data yes An array of new filters to set on the topic.

Data Child Parameters

Parameter Required Description
type yes The type of filter to set.
phrase yes The value required by the specific filter type.

Available Filters Types

Type Value Description
include phrase Phrase that must be included somewhere in the results.
exclude phrase Phrase that must not be included somewhere in the results.
nsfw phrase Automatically adds a list of Not Safe For Work terms as exclude filters. Phrase should be passed as null or empty string.

Returns

Field Data Type Description
errors array A list of errors for filters that were unable to be set.
filters array A list of filters that were successfully set on the topic.

Error Messages

Message Description
Invalid topic The topic token provided was not valid.
Invalid filter-type: type The filter-type provided was invalid. Refer to ‘available filter types’ above for reference.
Filter already added The topic already contains the provided filter.

Clone Topic

require 'rest_client'

response = RestClient.post 'https://api.backstit.ch/v2/topics/868892907e0d01327760482a14180728/clone.json', {:key => '70b5aa707ca6013231ce482a14180728', 'topic_tokens[]' => [{:token => '9b5d30a07d4001325ede482a14180728'}]}
curl https://api.backstit.ch/v2/topics/868892907e0d01327760482a14180728/clone \
  -d 'key=70b5aa707ca6013231ce482a14180728&topic_tokens[][token]=9b5d30a07d4001325ede482a1418072'

The above command returns JSON structured like this:

{
  "id": 23949,
  "name": "Local Detroit News clone",
  "description": null,
  "banner": null,
  "token": "868892907e0d01327760482a14180728",
  "sources": [
    {
      "id": 78,
      "name": "Facebook Posts from backstitchapp",
      "icon": {
        "url": "http://graph.facebook.com/373050736086342/picture",
        "width": 50,
        "height": 50
      },
      "banner": {
        "url": "http://images-backstitch.s3.amazonaws.com/next/service_catalog/facebook_banner.jpg",
        "width": 650,
        "height": 240
      },
      "params": {
        "user": {
          "type": "search_term",
          "value": "backstitchapp"
        }
      },
      "filters": [
        {
          "id": 13419,
          "value": "detroit",
          "type": "include"
        }
      ],
      "service": "facebook_user"
    }
  ],  
  "filters": [
    {
      "id": 3244,
      "phrase": "Captain America",
      "type": "include"
    }
  ],
  "errors": []
}

Possible error messages:

{
  "message": "Invalid topic",
}
{
  "message": "Invalid topic",
  "token": '868892907e0d01327760482a14180728',
}

This endpoint enables cloning of sources and filters from a list of other topics. This is a great way to setup templates for your topics or to build user-specific streams.

HTTP Request

POST https://api.backstit.ch/v2/topics/{TOPIC_TOKEN}/clone

URL Parameters

Parameter Required Description
TOPIC_TOKEN yes The API token for the topic that you want to modify. The token generated from adding the API add-on from the topic editor or returned by the Create Topic endpoint.

Query Parameters

Parameter Required Default Description
key yes Your organization’s api key is obtained from the organization dashboard under settings.
topic_tokens yes A list of API tokens for the topics to copy sources and filters from.

Topic Token Child Parameters

Parameter Required Default Description
token yes The API token of the topic to be copied.

UnClone Topic

require 'rest_client'

response = RestClient.post 'https://api.backstit.ch/v2/topics/868892907e0d01327760482a14180728/unclone.json', {:key => '70b5aa707ca6013231ce482a14180728', 'topic_tokens[]' => [{:token => '9b5d30a07d4001325ede482a14180728'}]}
curl https://api.backstit.ch/v2/topics/868892907e0d01327760482a14180728/unclone \ 
  -d 'key=70b5aa707ca6013231ce482a14180728&topic_tokens[][token]=9b5d30a07d4001325ede482a14180728'

The above command returns JSON structured like this:

{
  "id": 23949,
  "name": "Local Detroit News clone",
  "description": null,
  "banner": null,
  "token": "868892907e0d01327760482a14180728",
  "sources": [],  
  "filters": [],
  "errors": []
}

Possible error messages:

{
  "message": "Invalid topic",
}
{
  "message": "Invalid topic",
  "token": '868892907e0d01327760482a14180728',
}

This endpoint enables removing the sources and filters that were cloned from other topics. This is a great way to maintain user-specific streams where subtopics can be unsubscribed.

HTTP Request

POST https://api.backstit.ch/v2/topics/{TOPIC_TOKEN}/unclone

URL Parameters

Parameter Required Description
TOPIC_TOKEN yes The API token for the topic that you want to modify. The token generated from adding the API add-on from the topic editor or returned by the Create Topic endpoint.

Query Parameters

Parameter Required Default Description
key yes Your organization’s api key is obtained from the organization dashboard under settings.
topic_tokens yes A list of API tokens for the topics to remove included sources and filters from this topic.

Topic Token Child Parameters

Parameter Required Default Description
token yes The API token of the topic to be removed.

Delete Topic Sources

require 'rest_client'
require 'active_support'

params = {:key => '70b5aa707ca6013231ce482a14180728' :data => [{:service => 'facebook_user', :value => 'backstitchapp'}]}

params_string = params.to_query

url = "https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/sources.json?#{params_string}"

response = RestClient.delete url
curl -X DELETE https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/sources \
  -d 'key=70b5aa707ca6013231ce482a14180728&data[][service]=facebook_user&data[][value]=backstitchapp'

The above command returns JSON structured like this:

{
  "errors":[],
  "sources":[
    {
      "filters":[],
      "id": 76,
      "name": "Facebook Posts from backstitchapp",
      "icon":{
        "url": "http://images-backstitch.s3.amazonaws.com/services/icons/facebook.png",
        "width": 64,
        "height": 64
      },
      "banner":{
        "url": "http://images-backstitch.s3.amazonaws.com/next/service_catalog/facebook_banner.jpg",
        "width": 650,
        "height": 240
      },
      "value": "backstitchapp",
      "service_name": "facebook_user"
    }
  ]
}

Possible error messages:

{
  "message": "Invalid topic"
}

{
  "message": "Invalid service: instagram_profile",
  "service": "instagram_profile",
  "value": "backstitch"
}

This endpoint removes sources from the topic.

HTTP Request

DELETE https://api.backstit.ch/v2/topics/{TOPIC_TOKEN}/sources

URL Parameters

Parameter Required Description
TOPIC_TOKEN yes The topic’s token generated from adding the API add-on from the topic editor or returned by the Create Topic endpoint.

Query Parameters

Parameter Required Default Description
key yes Your organization’s api key obtained from the organization dashboard.
data yes An array of sources to remove from your topic.

Data Child Parameters

Parameter Required Default Description
service yes The name of the source to remove’s service.
value yes The value of the source to remove’s service.

Available Services

Reference the list of available services under the Add Topic Sources section.

Returns

Field Data Type Description
errors array A list of errors for sources that were not removed
sources array A list of sources that were removed

Error Messages

Message Description
Invalid topic The topic token provided was not valid.
Invalid service: service The service provided is not valid. Refer to ‘available services’ above for reference.

Delete Topic Filters

require 'rest_client'
require 'active_support'

params = {:key => '70b5aa707ca6013231ce482a14180728', :data => [{:type => 'include', :phrase => 'downtown'}]}

params_string = params.to_query

url = "https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/filters.json?#{params_string}"

response = RestClient.delete url
curl -X DELETE https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/filters \
  -d 'key=c7f6e1707f090132fe5a50e140978a72&data[][type]=include&data[][phrase]=detroit'

The above command returns JSON structured like this:

{
  "errors":[],
  "filters":[
    {
      "id": 345,
      "phrase": "downtown",
      "type": "include"
    }
  ]
}

Possible error messages:

{
  "message": "Invalid topic"
}

{
  "message": "No such filter",
  "type": "include",
  "phrase": "detroit"
}

This endpoint removes global filters from the topic.

HTTP Request

DELETE https://api.backstit.ch/v2/topics/{TOPIC_TOKEN}/filters

URL Parameters

Parameter Required Description
TOPIC_TOKEN yes The topic’s token generated from adding the API add-on from the topic editor or returned by the Create Topic endpoint.

Query Parameters

Parameter Required Default Description
key yes Your organization’s api key obtained from the organization dashboard.
data yes An array of filters to remove.

Data Child Parameters

Parameter Required Default Description
type yes The filter type.
phrase yes The value of the filter.

Available Filters

Reference the list of available services under the Add Topic Filters section.

Returns

Field Data Type Description
errors array A lits of errors for why certain filters were unable to be removed.
filters array A list of global keyword that were removed.

Error Messages

Message Description
Invalid topic The topic token provided was invalid.
No such filter The filter provided for removal does not exist for the topic.

Delete Topic

require 'rest_client'

response = RestClient.delete 'https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728.json?key=70b5aa707ca6013231ce482a14180728'
curl -X DELETE https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728 /
  -d 'key=70b5aa707ca6013231ce482a14180728'

The above command returns JSON structured like this:

{
  "id": 13,
  "name": "Detroit",
  "description": "",
  "banner": {
    "url": "http://images-backstitch.s3.amazonzws.com/next/logos/backstitch_purple_icon.png",
    "width": 300,
    "height": 300
  },
  "token": "9b5d30a07d4001325ede482a14180728",
  "filters": [],
  "sources":[]
}

Possible error messages:

{
  "message": "Invalid topic"
}

This endpoint deletes the topic.

HTTP Request

DELETE https://api.backstit.ch/v2/topics/{TOPIC_TOKEN}

URL Parameters

Parameter Required Description
TOPIC_TOKEN yes The topic’s token generated from adding the API add-on from the topic editor or returned by the Create Topic endpoint.

Query Parameters

Parameter Required Default Description
key yes Your organization’s api key obtained from the organization dashboard.

Returns

Returns details about the now deleted topic. This is done for your app’s reference (such as for updating your UI once a topic has been deleted).

Field Data Type Description
id integer A unique identifier for the topic
name string The name given to the topic
description string An optional description of the topic
banner object The topic’s displayed banner image if one was uploaded
token string The topic’s api token
filters array A list of global keyword filters set on the topic
sources array A list of included sources

Error Messages

Message Description
Invalid topic The topic token provided was not valid.

Get Topic Details

require 'rest_client'

response = RestClient.get 'https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728.json'
curl https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728

The above command returns JSON structured like this:

{
  "id": 13,
  "name": "Detroit",
  "description": "",
  "banner": {
    "url": "http://images-backstitch.s3.amazonzws.com/next/logos/backstitch_purple_icon.png",
    "width": 300,
    "height": 300
  },
  "token": "9b5d30a07d4001325ede482a14180728",
  "filters": [
    {
      "id": 345,
      "phrase": "downtown",
      "type": "include"
    }
  ],
  "sources": [
    {
      "filters":[],
      "id": 76,
      "name": "Facebook Posts from backstitchapp",
      "icon":{
        "url": "http://images-backstitch.s3.amazonaws.com/services/icons/facebook.png",
        "width": 64,
        "height": 64
      },
      "banner":{
        "url": "http://images-backstitch.s3.amazonaws.com/next/service_catalog/facebook_banner.jpg",
        "width": 650,
        "height": 240
      },
      "value": "backstitchapp",
      "service_name": "facebook_user"
    }
  ]
}

Possible error messages:

{
  "message": "Invalid topic"
}

{
  "message": "Add-on not activated",
  "call-type": "widget"
}

This endpoint retrieves details about a topic.

HTTP Request

GET https://api.backstit.ch/v2/topics/{TOPIC_TOKEN}

URL Parameters

Parameter Required Description
TOPIC_TOKEN yes The topic’s token generated from adding the API add-on from the topic editor or returned by the Create Topic endpoint.

Returns

Field Data Type Description
id integer A unique identifier for the topic.
name string The name given to the topic.
description string An optional description of the topic,
banner object The topic’s displayed banner image if one was uploaded.
token string The topic’s api token.
filters array A list of global filters set on the topic.
sources array A list of included sources.

Error Messages

Message Description
Invalid topic The topic token provided was not valid.
Add-on not activated The topic does not have either the API or Widget add-ons enabled.

Retrieve Topic Results

require 'rest_client'

# Retrieve latest results
response = RestClient.get 'https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/results'

# Retrieve second page of latest results
response = RestClient.get 'https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/results', :params => {:skip => 20} 

# Retrieve results published between two dates
response = RestClient.get 'https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/results', :params => {:skip => 20, :min_date => '2015-07-01', :max_date => '2015-07-15'}

# Retrieve results published after a specific article was published
response = RestClient.get 'https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/results', :params => {:skip => 20, :min_id => '6dd447800d1b0133b29950e140978a72'}

# Search Results
response = RestClient.get 'https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/results', :params => {:term => 'restaurants'} 

# Search for results published after a certain date
response = RestClient.get 'https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/results', :params => {:min_date => '2015-07-01', :term => 'restaurants'}
# Retrieve latest results
curl https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/results

# Retrieve second page of latest results
curl https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/results&skip=20"

# Retrieve results between two dates
curl https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/results?max_date=2015-07-15&min_date=2015-07-01"

# Retrieve results published after a specific article was published
curl https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/results?max_date=2015-07-15&min_id=6dd447800d1b0133b29950e140978a72"

# Search Results
curl https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/results&term=restaurants"

# Search for results published after a certain date
curl https://api.backstit.ch/v2/topics/9b5d30a07d4001325ede482a14180728/results?min_date=2015-07-01&term=restaurants"

The above command returns JSON structured like this:

[{
  "id": "2ee995b07cb201323db11aa32735a1a3",
  "type": "article",
  "title": "Renderings Revealed: Glass-Enclosed Restaurant & Patio Planned Downtown",
  "description": "Townhouse already announced plans for a new downtown Detroit location, but Eater Detroit has revealed that the Birmingham-based restaurant aspires to go beyond simply filling an empty storefront. Complete with a retractable roof, Townhouse Detroit plans to build a...",
  "full_text": "<div><p>[McIntosh Poris/Townhouse]  </p><p><strong>Townhouse</strong> already <a href=\"http://detroit.eater.com/2014/11/3/7148533/birminghams-townhouse-restaurant-is-headed-for-detroit\">announced</a> plans for a new downtown Detroit location, but <a href=\"http://detroit.eater.com/2015/1/8/7510471/townhouse-plans-greenhouse-style-dining-room-for-detroit-and-open-air\">Eater Detroit</a> has revealed that the Birmingham-based restaurant aspires to go beyond simply filling an empty storefront. Complete with a retractable roof, Townhouse Detroit plans to build a <strong>greenhouse-like dining room</strong> right next to One Detroit Center with seating for 120.</div>",
  "plain_text": "Townhouse already announced plans for a new downtown Detroit location, but Eater Detroit has revealed that the Birmingham-based restaurant aspires to go beyond simply filling an empty storefront. Complete with a retractable roof, Townhouse Detroit plans to build a greenhouse-like dining room right next to One Detroit Center with seating for 120.",
  "author": {
    "name": "Paul Beshouri"
  },
  "published_at": "2015-01-12T17:42:11Z",
  "images": {
    "thumbnail": {
      "url": null,
      "width": null,
      "height": null
    },
    "full_size": {
      "url": "http://detroit.curbed.com/uploads/townhouse1-thumb.jpg",
      "width": null,
      "height": null
    },
    "other": []
  },
  "source": {
    "id": null,
    "name": null,
    "description": null,
    "url": null,
    "icon": {
      "url": null,
      "width": null,
      "height": null
    }
  },
  "origin": {
    "id": null,
    "name": "Curbed Detroit",
    "url": "http://detroit.curbed.com/archives/2015/01/glassenclosed-restaurant-patio-planned-downtown.php",
    "icon": {
      "url": "http://curbed.com/favicon.ico",
      "width": 16,
      "height": 16
    }
  }
}]

This endpoint retrieves results from the topic. By default all results are returned in descending order by the date that the content was originally published. If a query is passed then the order is based on the most relevent match to the query.

HTTP Request

GET https://api.backstit.ch/v2/topics/{TOPIC_TOKEN}/results

URL Parameters

Parameter Required Description
TOPIC_TOKEN yes The topic’s token generated from adding the API add-on from the topic editor or returned by the Create Topic endpoint.

Query Parameters

Parameter Required Default Description
count no 20 The number of results to return per call, up to a maximum of 50.
skip no 0 The number of results to skip per call, to be used for paging.
term no This will return results that are most relevant to the passed term.
max_date no This will return results that were published before the given date (accepts epoch integer time or ISO 8601 formatted datetime)
min_date no This will return results that were published after the given date (accepts epoch integer time or ISO 8601 formatted datetime)
max_id no This will return results that were published before the result with the given id.
min_id no This will return results that were published after the result with the given id.
suppress_duplicates no false Passing true will attempt to only return unique results. It is highly recommended to request results by date or by ID rather than using skip and count while suppressing duplicates.

Returns

An array of results. Consult the Result Type Dictionary for field descriptions.

Post Results to Custom Sources

require 'rest_client'

# Post a link

RestClient.post 'https://api.backstit.ch/v2/organizations/9211967035420133bff950e140978a72/post', {:feed_name => "Internal Feed", :type => 'link', :url => 'https://medium.com/backstitch-inc/100-industries-over-100-days-7521e75027ff', :email => 'api_example@backstit.ch'}

# Post an image

RestClient.post 'https://api.backstit.ch/v2/organizations/9211967035420133bff950e140978a72/post', {:feed_name => "Internal Feed", :type => 'image', :image => 'https://images-backstitch.s3.amazonaws.com/next/logos/backstitch_white_small.png', :description => 'The backstitch logo in white', :email => 'api_example@backstit.ch'}

# Post a text post

RestClient.post 'https://api.backstit.ch/v2/organizations/9211967035420133bff950e140978a72/post', {:feed_name => "Internal Feed", :type => 'text', :text => "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum." , :title => 'Example Text Post', :email => 'api_example@backstit.ch'}

# Post a link
curl -X POST  https://api.backstit.ch/v2/organizations/9211967035420133bff950e140978a72/post?type=link&url=https%3A%2F%2Fmedium.com%2Fbackstitch-inc%2F100-industries-over-100-days-7521e75027ff&email=api_example%40backstit.ch&feed_name=Test+Source

# Post an image
curl -X POST  https://api.backstit.ch/v2/organizations/9211967035420133bff950e140978a72/post?type=image&image=https%3A%2F%2Fimages-backstitch.s3.amazonaws.com%2Fnext%2Flogos%2Fbackstitch_white_small.png&description=The+backstitch+logo+in+white&email=api_example%40backstit.ch&feed_name=Test+Source

# Post a text post
curl -X POST  https://api.backstit.ch/v2/organizations/9211967035420133bff950e140978a72/post?type=text&title=Test%20title&text=Lorem+ipsum+dolor+sit+amet%2C+consectetur+adipiscing+elit%2C+sed+do+eiusmod+tempor+incididunt+ut+labore+et+dolore+magna+aliqua.+Ut+enim+ad+minim+veniam%2C+quis+nostrud+exercitation+ullamco+laboris+nisi+ut+aliquip+ex+ea+commodo+consequat.+Duis+aute+irure+dolor+in+reprehenderit+in+voluptate+velit+esse+cillum+dolore+eu+fugiat+nulla+pariatur.+Excepteur+sint+occaecat+cupidatat+non+proident%2C+sunt+in+culpa+qui+officia+deserunt+mollit+anim+id+est+laborum&email=api_example%40backstit.ch&feed_name=Test+Source

This endpoint allows you to post to custom sources. These posts will appear in all topics that the custom source has been added to.

HTTP Request

POST https://api.backstit.ch/v2/organizations/{ORGANIZATION_KEY}/post

URL Parameters

Parameter Required Description
ORGANIZATION_KEY yes Your organization’s api key is obtained from the organization dashboard under settings.

Query Parameters

These parameters are required regardless of the post type.

Parameter Required Description
feed_name yes The name of the custom feed that will be posted to.
type yes The type of post that is being posted to the feed (text, image, or link). Note: Different parameters are required for each type of post (see below).
email yes The email address of the user that will be credited for the post.
Parameter Required Description
url yes The URL of the article that you would like to be scraped for the post.
title no The title of the post. Note: If none is provided, backstitch will attempt to scrape the article’s title from the source.

Image Parameters

Parameter Required Description
image yes The URL of the image that you would like added to the post.
description no A short description of the image provided.

Text Parameters

Parameter Required Description
text yes The actual content of the post. This can be either plain-text or HTML.
title yes The title of the post.

API 1.0 Endpoints

require 'rest_client'

response = RestClient.get 'https://api.backstit.ch/v1/topic/details.json', :params => {:token => '9523280292F046269CD4C2F8C'}
# GET https://api.backstit.ch/v1/topic/details.json?token={topic_token}
curl https://api.backstit.ch/v1/topic/details.json \
  -d 'token=9523280292F046269CD4C2F8C'

Make sure to replace 9523280292F046269CD4C2F8C with your topic’s token.

All API 1.0 requests use the base url of https://api.backstit.ch/v1/topic and authenticate by passing the topic’s token as query a parameter.

Get Topic Details

require 'rest_client'

response = RestClient.get 'https://api.backstit.ch/v1/topic/details.json', :params => {:token => '9523280292F046269CD4C2F8C'}
curl https://api.backstit.ch/v1/topic/details.json \
  -d 'token=9523280292F046269CD4C2F8C'

The above command returns JSON structured like this:

{
  "uid": 821,
  "name": "Detroit",
  "description": "A topic with stories about Detroit.",
  "banner": {
    "url": "http://backstitch-user-uploads.s3.amazonaws.com/production/topic_banners/16427_1400578046.jpg",
    "width": 650,
    "height" :240
  },
  "api_token": "9523280292F046269CD4C2F8C",
  "filters": [
    {
      "uid":56,
      "phrase":"detroit"
    }
  ],
  "feeds": [
    {
      "uid": 13624,
      "name": "CNN",
      "icon": {
        "url": "http://images-backstitch.s3.amazonaws.com/next/service_catalog/cnn_icon.png",
        "width": "16",
        "height": "16"
      },
      "banner": {
        "url": "http://images-backstitch.s3.amazonaws.com/next/service_catalog/cnn_banner.jpg",
        "width": "650",
        "height": "240"
      },
      "service_name": "RSS"
    },
    {
      "uid": 13666,
      "name": "Tweets tagged detroit",
      "icon": {
        "url": "http://images-backstitch.s3.amazonaws.com/next/service_catalog/twitter_icon.png",
        "width": "16",
        "height": "16"
      },
      "banner": {
        "url": "http://images-backstitch.s3.amazonaws.com/next/service_catalog/twitter_banner.jpg",
        "width": "650",
        "height": "240"
      },
      "service_name": "Twitter"
    }
  ]
}

This endpoint retrieves details about a topic.

HTTP Request

GET https://api.backstit.ch/v1/topic/details.json

Query Parameters

Parameter Required Description
token yes To obtain a token, you must first log into backstitch and from the topic editor include the API add-on. This will generate a secure token to identify the topic.

Returns

Field Data Type Description
uid integer A unique identifier for the topic
name string The name given to the topic
description string An optional description of the topic
banner object The topic’s displayed banner image if one was uploaded
api_token string The topic’s api token
filters array A list of global keyword filters set on the topic
feeds array A list of included feeds

Fetch Topic Results

require 'rest_client'

response = RestClient.get 'https://api.backstit.ch/v1/topic/fetch.json', :params => {:token => '9523280292F046269CD4C2F8C'}
curl https://api.backstit.ch/v1/topic/fetch.json \
  -d "token=9523280292F046269CD4C2F8C"

The above command returns JSON structured like this:

[{
  "id": "2ee995b07cb201323db11aa32735a1a3",
  "type": "article",
  "title": "Renderings Revealed: Glass-Enclosed Restaurant & Patio Planned Downtown",
  "description": "Townhouse already announced plans for a new downtown Detroit location, but Eater Detroit has revealed that the Birmingham-based restaurant aspires to go beyond simply filling an empty storefront. Complete with a retractable roof, Townhouse Detroit plans to build a...",
  "full_text": "<div><p>[McIntosh Poris/Townhouse]  </p><p><strong>Townhouse</strong> already <a href=\"http://detroit.eater.com/2014/11/3/7148533/birminghams-townhouse-restaurant-is-headed-for-detroit\">announced</a> plans for a new downtown Detroit location, but <a href=\"http://detroit.eater.com/2015/1/8/7510471/townhouse-plans-greenhouse-style-dining-room-for-detroit-and-open-air\">Eater Detroit</a> has revealed that the Birmingham-based restaurant aspires to go beyond simply filling an empty storefront. Complete with a retractable roof, Townhouse Detroit plans to build a <strong>greenhouse-like dining room</strong> right next to One Detroit Center with seating for 120.</div>",
  "plain_text": "Townhouse already announced plans for a new downtown Detroit location, but Eater Detroit has revealed that the Birmingham-based restaurant aspires to go beyond simply filling an empty storefront. Complete with a retractable roof, Townhouse Detroit plans to build a greenhouse-like dining room right next to One Detroit Center with seating for 120.",
  "author": {
    "name": "Paul Beshouri"
  },
  "published_at": "2015-01-12T17:42:11Z",
  "images": {
    "thumbnail": {
      "url": null,
      "width": null,
      "height": null
    },
    "full_size": {
      "url": "http://detroit.curbed.com/uploads/townhouse1-thumb.jpg",
      "width": null,
      "height": null
    },
    "other": []
  },
  "source": {
    "id": null,
    "name": null,
    "description": null,
    "url": null,
    "icon": {
      "url": null,
      "width": null,
      "height": null
    }
  },
  "origin": {
    "id": null,
    "name": "Curbed Detroit",
    "url": "http://detroit.curbed.com/archives/2015/01/glassenclosed-restaurant-patio-planned-downtown.php",
    "icon": {
      "url": "http://curbed.com/favicon.ico",
      "width": 16,
      "height": 16
    }
  }
}]

This endpoint fetches the latest results from the topic. All results are in descending order by the date that the content was originally published.

HTTP Request

GET https://api.backstit.ch/v1/topic/fetch.json

Query Parameters

Parameter Required Default Description
token yes To obtain a token, you must first log into backstitch and from the topic editor include the API add-on. This will generate a secure token to identify the topic.
count no 20 The number of results to return per call, up to a maximum of 50.
skip no 0 The number of results to skip per call, to be used for paging.

Returns

An array of results. Consult the Result Type Dictionary for field descriptions.

Filter Topic Results

require 'rest_client'

response = RestClient.get 'https://api.backstit.ch/v1/topic/fetch.json', :params => {:token => '9523280292F046269CD4C2F8C', :term => 'restaurants'}
curl https://api.backstit.ch/v1/topic/fetch.json \
  -d "token=9523280292F046269CD4C2F8C&term=restaurants"

The above command returns JSON structured like this:

[{
  "id": "2ee995b07cb201323db11aa32735a1a3",
  "type": "article",
  "title": "Renderings Revealed: Glass-Enclosed Restaurant & Patio Planned Downtown",
  "description": "Townhouse already announced plans for a new downtown Detroit location, but Eater Detroit has revealed that the Birmingham-based restaurant aspires to go beyond simply filling an empty storefront. Complete with a retractable roof, Townhouse Detroit plans to build a...",
  "full_text": "<div><p>[McIntosh Poris/Townhouse]  </p><p><strong>Townhouse</strong> already <a href=\"http://detroit.eater.com/2014/11/3/7148533/birminghams-townhouse-restaurant-is-headed-for-detroit\">announced</a> plans for a new downtown Detroit location, but <a href=\"http://detroit.eater.com/2015/1/8/7510471/townhouse-plans-greenhouse-style-dining-room-for-detroit-and-open-air\">Eater Detroit</a> has revealed that the Birmingham-based restaurant aspires to go beyond simply filling an empty storefront. Complete with a retractable roof, Townhouse Detroit plans to build a <strong>greenhouse-like dining room</strong> right next to One Detroit Center with seating for 120.</div>",
  "plain_text": "Townhouse already announced plans for a new downtown Detroit location, but Eater Detroit has revealed that the Birmingham-based restaurant aspires to go beyond simply filling an empty storefront. Complete with a retractable roof, Townhouse Detroit plans to build a greenhouse-like dining room right next to One Detroit Center with seating for 120.",
  "author": {
    "name": "Paul Beshouri"
  },
  "published_at": "2015-01-12T17:42:11Z",
  "images": {
    "thumbnail": {
      "url": null,
      "width": null,
      "height": null
    },
    "full_size": {
      "url": "http://detroit.curbed.com/uploads/townhouse1-thumb.jpg",
      "width": null,
      "height": null
    },
    "other": []
  },
  "source": {
    "id": null,
    "name": null,
    "description": null,
    "url": null,
    "icon": {
      "url": null,
      "width": null,
      "height": null
    }
  },
  "origin": {
    "id": null,
    "name": "Curbed Detroit",
    "url": "http://detroit.curbed.com/archives/2015/01/glassenclosed-restaurant-patio-planned-downtown.php",
    "icon": {
      "url": "http://curbed.com/favicon.ico",
      "width": 16,
      "height": 16
    }
  }
}]

This endpoint filters the results from the topic based on a passed term. All results are in descending order with the most relevent match first.

HTTP Request

GET https://api.backstit.ch/v1/topic/filter.json

Query Parameters

Parameter Required Default Description
token yes To obtain a token, you must first log into backstitch and from the topic editor include the API add-on. This will generate a secure token to identify the topic.
term yes This will return results that are most relevant to the passed term.
count no 20 The number of results to return per call, up to a maximum of 50.
skip no 0 The number of results to skip per call, to be used for paging.

Returns

An array of results. Consult the Result Type Dictionary for field descriptions.

Result Type Dictionary

Topic results follow a standard schema based on type regardless of the original source of the content.

Article

{
  "id": "2ee995b07cb201323db11aa32735a1a3",
  "type": "article",
  "title": "Renderings Revealed: Glass-Enclosed Restaurant & Patio Planned Downtown",
  "description": "Townhouse already announced plans for a new downtown Detroit location, but Eater Detroit has revealed that the Birmingham-based restaurant aspires to go beyond simply filling an empty storefront. Complete with a retractable roof, Townhouse Detroit plans to build a...",
  "full_text": "<div><p>[McIntosh Poris/Townhouse]  </p><p><strong>Townhouse</strong> already <a href=\"http://detroit.eater.com/2014/11/3/7148533/birminghams-townhouse-restaurant-is-headed-for-detroit\">announced</a> plans for a new downtown Detroit location, but <a href=\"http://detroit.eater.com/2015/1/8/7510471/townhouse-plans-greenhouse-style-dining-room-for-detroit-and-open-air\">Eater Detroit</a> has revealed that the Birmingham-based restaurant aspires to go beyond simply filling an empty storefront. Complete with a retractable roof, Townhouse Detroit plans to build a <strong>greenhouse-like dining room</strong> right next to One Detroit Center with seating for 120.</div>",
  "plain_text": "Townhouse already announced plans for a new downtown Detroit location, but Eater Detroit has revealed that the Birmingham-based restaurant aspires to go beyond simply filling an empty storefront. Complete with a retractable roof, Townhouse Detroit plans to build a greenhouse-like dining room right next to One Detroit Center with seating for 120.",
  "author": {
    "name": "Paul Beshouri"
  },
  "published_at": "2015-01-12T17:42:11Z",
  "images": {
    "thumbnail": {
      "url": null,
      "width": null,
      "height": null
    },
    "full_size": {
      "url": "http://detroit.curbed.com/uploads/townhouse1-thumb.jpg",
      "width": null,
      "height": null
    },
    "other": []
  },
  "source": {
    "id": null,
    "name": null,
    "description": null,
    "url": null,
    "icon": {
      "url": null,
      "width": null,
      "height": null
    }
  },
  "origin": {
    "id": null,
    "name": "Curbed Detroit",
    "url": "http://detroit.curbed.com/archives/2015/01/glassenclosed-restaurant-patio-planned-downtown.php",
    "icon": {
      "url": "http://curbed.com/favicon.ico",
      "width": 16,
      "height": 16
    }
  }
}

An article most likely from an RSS feed or posted on social media. Contains the full content in both plain text and HTML formatted.

Field Data Type Description
id string A unique identifier for the result
type string The type of the result
title string The article’s title
description string An article summary or lede paragraph which may end with an ellipsis
full_text string If available the main contents of the article with HTML formatting and embedded media
plain_text string If available the main contents of the article without any tags or media
comments_url string If available a link to this article’s comments
author object If available the name of the article’s author
published_at string The date that the article was originally published in UTC
images array If available the article’s main images
source object If the article came from social media this contains the information about the user that posted it
origin object Details about the website that hosts this article

Status

{
  "id": "70f56ca07ccf01328e7156f4f15407e1",
  "type": "status",
  "description": "What are your plans for the New Year? #NYE2015",
   "published_at": "2014-31-12T17:42:11Z",
  "location": {
    "lat_lon": null,
    "street_address": null,
    "city": null,
    "region_name": null,
    "zipcode": null,
    "country": null,
    "country_code": null,
    "woeid": null,
    "latitude": null,
    "longitude": null
  },
  "source": {
    "id": "23213213",
    "name": "backstitch",
    "description": null,
    "url": "http://twitter.com/backstitch",
    "icon": {
      "url": "https://pbs.twimg.com/profile_images/488756158694318080/6BiMMFOf_400x400.png",
      "width": 400,
      "height": 400
    }
  },
  "origin": {
    "id": "2423423",
    "name": "Twitter",
    "url": "http://twitter.com",
    "icon": {
      "url": "http://images-backstitch.s3.amazonaws.com/next/service_catalog/twitter_icon.png",
      "width": 16,
      "height": 16
    }
  }
}

A short form user-generated message most likely posted on social media.

Field Data Type Description
id string A unique identifier for the result
type string The type of the result
description string The contents of the status message
published_at string The date that the status was originally posted in UTC
location object If available the geolocation of where the post was made
source object Details about the user that posted the message
origin object Details about the website that the user posted on

Photo

{
  "id": "63dc7a6082460132f50d1aa7948f105d",
  "type": "photo",
  "description": "#MadCatz L.Y.N.X. 9 – a #transforming #controller for your #Android #devicesSee here- http://in.gamerekon.com/?p=3824",
  "published_at": "2015-01-19T12:49:25+00:00",
  "images": {
    "thumbnail": {
      "url": "http://scontent-a.cdninstagram.com/hphotos-xaf1/t51.2885-15/s150x150/e15/10903762_787557491324190_1049615505_n.jpg",
      "width": 150,
      "height": 150
    },
    "full_size": {
      "url": "http://scontent-a.cdninstagram.com/hphotos-xaf1/t51.2885-15/e15/10903762_787557491324190_1049615505_n.jpg",
      "width": 640,
      "height": 640
    },
    "other": []
  },
  "location": {
    "lat_lon": null,
    "street_address": null,
    "city": null,
    "region_name": null,
    "zipcode": null,
    "country": null,
    "country_code": null,
    "woeid": null,
    "latitude": null,
    "longitude": null
  },
  "source": {
    "id": "1596774574",
    "name": "gamerekonindia",
    "description": null,
    "url": "www.instagram.com/gamerekonindia",
    "icon": {
      "url": "https://igcdn-photos-h-a.akamaihd.net/hphotos-ak-xaf1/t51.2885-19/10852941_1570019279899463_61316027_a.jpg",
      "width": 150,
      "height": 150
    }
  },
  "origin": {
    "id": "901370557046947610_1596774574",
    "name": "instagram",
    "url": "http://instagram.com/p/yCT773x38a/",
    "icon": {
      "url": "http://images-backstitch.s3.amazonaws.com/next/service_catalog/instagram_icon.png",
      "width": "64",
      "height": "64"
    }
  },
  "comments_url": null
}

A photo most likely from a hosted service such as Flickr or posted to social media.

Field Data Type Description
id string A unique identifier for the result
type string The type of the result
description string A description or caption of the photo
published_at string The date that the photo was originally published in UTC
images object Different sizes of the photo available
location object If available the geolocation of where the photo was published from
comments_url string If available a link to this photo’s comments
source object If available details about the user that posted the photo
origin object Details about the website that hosts this photo

Video

{
  "id": "b322fa407d7c0132ccb81a238d96d9fe",
  "type": "video",
  "title": "Honest Trailers - Gone Girl",
  "description": "Screen Junkies approved! Watch feature-length movies for free on Break ►► <a href=\"http://brk.cm/MoviesonBreak\">http://brk.cm/MoviesonBreak</a>\nBecome a Screen Junkie! ►► <a href=\"http://bit.ly/sjsubscr\">http://bit.ly/sjsubscr</a>\nWatch more Honest Trailers ►► <a href=\"http://bit.ly/HonestTrailerPlaylist\">http://bit.ly/HonestTrailerPlaylist</a>\n\nGet ready to cower in terror as you relive David Fincher's married-people version of Fatal Attraction: Gone Girl.\n\nGot a tip? Email us ► <a href=\"mailto:tips@screenjunkies.com\">tips@screenjunkies.com</a>\nFollow us on Twitter ► <a href=\"http://twitter.com/screenjunkies\">http://twitter.com/screenjunkies</a>\nLike us on Facebook ► <a href=\"http://www.fb.com/screenjunkies\">http://www.fb.com/screenjunkies</a>\n\nVoiceover Narration by Jon: <a href=\"http://youtube.com/jon3pnt0\">http://youtube.com/jon3pnt0</a>\n\nTitle design by Robert Holtby\n\nOriginal music by Sean Motley\n\nSeries Created by Andy Signore <a href=\"http://twitter.com/andysignore\">http://twitter.com/andysignore</a> & Brett Weiner\nWritten by Dan Murrell, Spencer Gilbert, and Andy Signore\nEdited by Dan Murrell\n---\n\nLet us know in the comments below what movie or TV show you want to see next!"
  "published_at": "2015-01-13T17:53:20Z",
  "url": "http://www.youtube.com/watch?v=l-1wldsq8_8",
  "embed_code": "<iframe type='text/html' src='http://www.youtube.com/embed/l-1wldsq8_8' width='640' height='360' frameborder='0' allowfullscreen='true'/>",
  "images": {
    "thumbnail": {
      "url": "https://i.ytimg.com/vi/l-1wldsq8_8/default.jpg",
        "width": 88,
        "height": 88
    },
    "full_size": {
      "url": "https://i.ytimg.com/vi/l-1wldsq8_8/hqdefault.jpg",
      "width": 480,
      "height": 360
    },
    "other": []
  },
  "location": {
    "lat_lon": null,
    "street_address": null,
    "city": null,
    "region_name": null,
    "zipcode": null,
    "country": null,
    "country_code": null,
    "woeid": null,
    "latitude": null,
    "longitude": null
  },
  "source": {
    "id": "UCOpcACMWblDls9Z6GERVi1A",
    "name": "Screen Junkies",
    "description": "In a world full of movies and television, only one channel is keeping them honest every Tuesday and Thursday - SCREEN JUNKIES! \n\nHome of the epic Honest Trailers and The ScreenJunkies Show...it's the ScreenJunkies YouTube channel!  Enjoy our warped take on film & TV with a steady stream of pop-culture parody, original series, thoughtful commentary, and whatever we can think of next.\n\nTuesdays: Honest Trailers\nThursdays: Screen Junkies Show\nSundays: Movie Fights, Powered by Schmoes Know Network",
    "url": "http://www.youtube.com/channel/UCOpcACMWblDls9Z6GERVi1A",
    "icon": {
      "url": "https://yt3.ggpht.com/-YmAo2aa3-nM/AAAAAAAAAAI/AAAAAAAAAAA/WqpO7AUlJUM/s88-c-k-no/photo.jpg",
      "width": 88,
      "height": 88
    }
  },
  "origin": {
    "id": "l-1wldsq8_8",
    "name": "YouTube",
    "url": "http://www.youtube.com/watch?v=l-1wldsq8_8",
    "icon": {
      "url": "http://images-backstitch.s3.amazonaws.com/next/service_catalog/youtube_icon.png",
      "width": "16",
      "height": "16"
    }
  },
  "comments_url": null
}

A video most likely from a hosted service such as YouTube or posted to social media.

Field Data Type Description
id string A unique identifier for the result
type string The type of the result
title string The title of the video
description string A longer description of the video
published_at string The date that the video was originally published in UTC
url string The direct url of the video
embed_code string Code to directly embed this video
images array If available preview images for the video
location object If available the geolocation of where the video was published from
comments_url string If available a link to this video’s comments
source object If available details about the user that posted the video
origin object Details about the website that hosts this video

Product

{
  "id": "ae2365d081f00132c59f72a99ca73d0a",
  "type": "product",
  "title": {
    "long": "$19 for the Batman Gotham Rising Fleece Blanket - Shipping Included",
    "short": null
  },
  "description": {
    "long": "<p>Batman is a favorite for both children and adults! What better way to express your love of the cartoon and film than with this warm fleece blanket. It measures 46&quot; x 60&quot; in size, and is made of 100% polyester. The blanket is an officially licensed product manufactured with superior quality by The Northwest Company. Get your warm and comfy blanket today <b>for $19, shipping included.</b></p>",
    "short": "Batman is a favorite for both children and adults! What better way to express your love of the cartoon and film than with this warm fleece blanket. It measures 46\" x 60\" in size, and is made of 100% polyester. The blanket is an officially licensed product manufactured with superior quality by The Northwest Company."
  },
  "published_at": "2015-01-19T09:00:00+00:00",
  "urls": {
    "info": "http://www.ncrowd.com/national/46484-avi-mfg-corp",
    "reviews": null,
    "purchase": null
  },
  "images": {
    "thumbnail": {
      "url": null,
      "width": null,
      "height": null
    },
    "full_size": {
      "url": "http://www.ncrowd.com/images/dynamic/deal/4/6/4/8/4/46484_lyMntF.png",
      "width": null,
      "height": null
    },
    "other": []
  },
  "price": {
    "value": "19",
    "display_value": null,
    "comparison_value": null,
    "iso_code": null,
    "name": null,
    "symbol": null
  },
  "fine_print": null,
  "model": null,
  "manufacturer": {
    "name": null,
    "url": null
  },
  "sku": null,
  "condition": null,
  "source": {
    "id": null,
    "name": null,
    "description": null,
    "url": null,
    "icon": {
      "url": null,
      "width": null,
      "height": null
    }
  },
  "origin": {
    "id": null,
    "name": "Deal Find",
    "url": "http://www.ncrowd.com/national/46484-avi-mfg-corp",
    "icon": {
      "url": "http://images-backstitch.s3.amazonaws.com/next/service_catalog/dealfind_icon.png",
      "width": "16",
      "height": "16"
    }
  }
}

A physical product most likely from an ecommerce or daily deal site.

Field Data Type Description
id string A unique identifier for the result
type string The type of the result
title object Contains both a short and long product name
description object Contains both a short and long product description
published_at string The date that the product was originally published in UTC
urls object Direct links to product information, reviews, and direct purchasing
images array A list of product images
price object The cost of the product
shipping_cost_ object If available the shipping cost of the product
fine_print string If available any additional fine-print details
model string If available the product model
manufacturer object If available the name the manufacturer and the url of their website
sku string If available the product’s SKU
condition string If available whether or not the product is new or used
source object If available details about the user that posted this product
origin object Details about the website that is selling this product

Service

{
  "id": "04e90fb07d1d0132aff626915c07c83a",
  "type": "service",
  "title": {
    "long": "$35 for $70 Toward Custom Dress Shirts from EPIC Shirtmakers ",
    "short": "50% Off Custom Dress Shirts"
  },
  "description": {
    "long": "<p></p>\n\n<h4>The Deal</h4>\n\n<ul>\n  <li>\n    <p>$35 for $70 toward <a href=\"http://epicshirtmakers.com/custom-tailored-dress-shirts\">custom dress shirts</a></p>\n  </li>\n  <li>\n    <p>Shirts start as low as $70 each.</p>\n  </li>\n</ul>",
    "short": "The Deal Shirts start as low as $70 each."
  },
  "full_text": null,
  "published_at": "2015-01-13T05:00:00Z",
  "urls": {
    "info": "http://www.groupon.com/deals/epic-shirtmakers-ann-arbor",
    "reviews": null,
    "purchase": "https://www.groupon.com/deals/epic-shirtmakers-ann-arbor/confirmation?pledge_id=12286850"
  },
  "images": {
    "thumbnail": {
      "url": "https://img.grouponcdn.com/deal/mXWCbsetzqqpp8gwBbUu/6Y-1500x900/v1/t50x50.jpg",
      "width": 50,
      "height": 50
    },
    "full_size": {
      "url": "https://img.grouponcdn.com/deal/mXWCbsetzqqpp8gwBbUu/6Y-1500x900/v1/t440x300.jpg",
      "width": 440,
      "height": 300
    },
    "other": []
  },
  "location": {
    "lat_lon": null,
    "street_address": null,
    "city": null,
    "region_name": null,
    "zipcode": null,
    "country": null,
    "country_code": null,
    "woeid": null,
    "latitude": null,
    "longitude": null
  },
  "price": {
    "value": 35,
    "display_value": null,
    "comparison_value": null,
    "iso_code": null,
    "name": null,
    "symbol": null
  },
  "fine_print": "Limit 1 per person, may buy 2 additional as gifts. Limit 1 per order. Online only. $12.99 shipping fee for single shirt orders. <b>Free shipping on orders of two or more shirts.</b>",
  "merchant": {
    "name": "EPIC Shirtmakers",
    "phone_number": null,
    "url": "http://epicshirtmakers.com"
  },
  "source": {
    "id": null,
    "name": null,
    "description": null,
    "url": null,
    "icon": {
      "url": null,
      "width": null,
      "height": null
    }
  },
  "origin": {
    "id": "epic-shirtmakers-ann-arbor",
    "name": "Groupon",
    "url": "http://www.groupon.com/deals/epic-shirtmakers-ann-arbor",
    "icon": {
      "url": "http://images-backstitch.s3.amazonaws.com/next/service_catalog/groupon_icon.png",
      "width": "16",
      "height": "16"
    }
  }
}

A professional service such as a restaurant.

Field Data Type Description
id string A unique identifier for the result
type string The type of the result
title object Contains both a short and long service name
description object Contains both a short and long service description
published_at string The date that this service was originally published in UTC
urls object Direct links to service information, reviews, and direct purchasing
images array A list of service images
location object If available the geolocation of where the service is available
price object The cost of the service
fine_print string If available any additional fine-print details
merchant object If available the name the merchant, their phone number, and the url of their website
source object If available details about the user that posted this service
origin object Details about the website that is selling this service

Hotel

{
  "id": "04996b507d300132ef4b32a97471a3dd",
  "type": "hotel",
  "title": {
    "long": "3-, 4-, or 7-Night Stay for Two in a One-Bedroom Villa at Acanto Boutique Hotel in Playa del Carmen, Mexico",
    "short": "4-Star Boutique Villas in Playa del Carmen"
  },
  "description": {
      "long": "<p></p>\n\n<h4>Four-Star Boutique Hotel Steps from Caribbean Sea</h4>\n\n<p>You won't see a car driving down Playa del Carmen's main thoroughfare, Quinta Avenida (or Fifth Avenue in English). Cars are off-limits here. Instead, live marimba musicians, pedestrians, fire-breathers, and vendors hawking handmade goods and Cuban cigars flood the cobblestone street. Less than a block from this lively main drag, the four-star Acanto Boutique Hotel puts you in prime position for exploring Playa del Carmen's Mayan architecture, checking out its hip nightlife, and kicking back on the Caribbean beaches that are just steps away.</p>\n\n<p>Tropical trees shade the hotel, which resembles a hacienda with wrought-iron terraces, arched windows, and an adobe façade. Walk down to the grotto-like courtyard to take a dip in a swimming pool surrounded by palm trees and stone siding, or head up to a rooftop hot tub to find ocean views. A marble bathroom, a terrace, and a full kitchen make each of the hotel's artfully designed one-bedroom villas feel luxurious and contemporary.</p>\n\n<p>If you want to pick up the pace, the concierge can set up eco-tours. Go scuba-diving along Playa del Carmen's massive barrier reef or swim with dolphins and teach them to whistle Creedence Clearwater Revival songs through their blowholes. You can also opt for horseback riding, ziplining through the jungle, or a day trip to the Mayan pyramid at Chichén Itzá.</p>\n\n<h4>Playa del Carmen, Mexico: Trendy Beach Area and Diving Destination</h4>\n\n<p>Just across the sea from the island of Cozumel, Playa del Carmen has been called \"the hippest city in all of the Yucatán Peninsula\" by Lonely Planet. The laid-back beach bars and cafés have a way of converting vacationers into expats, but Playa's most compelling draw might be its cenotes—cavernous sinkholes filled with turquoise pools. The water in the cenotes is crystal clear, particularly at the lily-pad-dotted Xlacah cenote, where you can snorkel among schools of colorful fish.</p>\n\n<p>To the south, you'll find preserved ruins of pre-Columbian cities. <a href=\"http://www.groupon.com/articles/tulum-mexico-swim-next-to-ancient-mayan-ruins-ga\">Tulum's</a> crumbling temples are situated above a dramatic ocean bluff, and Coba's enormous pyramid rises between two lagoons. For a fun day trip, hop aboard the ferry to Cozumel, which docks about a 15-minute walk from the hotel at the pier east of Calle 1. There are about a dozen dive shops on Cozumel, and they offer trips offshore to the reefs that Jacques Cousteau declared some of the world's most beautiful.</p>\n\n<hr />\n\n<h3>Frequently Asked Questions</h3>\n\n<p><strong>1. What is the best way to travel to the hotel from the airport?</strong> A shuttle from Cancún International Airport (CUN) is available for $140 roundtrip for up to six people.<br /></p>\n\n<p><strong>2. Is there an additional occupancy fee, or do I have to purchase another Groupon?</strong> The Groupon covers two guests. Adding an occupant above standard is $75 per night for an additional guest 13 or older; $55 per night for an additional guest 3–12; a kid 2 or younger stays free.<br /></p>\n\n<p><strong>3. Will I be approached to attend a timeshare sales presentation?</strong> Groupon customers are never obligated to attend a sales presentation. If you are approached and decline a presentation, you will not lose the value of your Groupon or have to pay additional fees.<br /></p>\n\n<p><strong>4. Which activities and amenities are included in the resort credits?</strong> Resort credits are not included with the Groupon.<br /></p>\n\n<p><strong>5. Are dinner reservations required for restaurants? Is there a dress code?</strong> For information regarding your dining options, please click <a href=\"http://www.acantohotels.com/dining/playa-del-carmen-dining-overview.htm\">here</a> or call 888-331-2177.<br /></p>\n\n<p><em>Love to travel? Follow us on <a href=\"http://gr.pn/17RUxNX\">Facebook</a> and <a href=\"http://gr.pn/1e9KPhk\">Twitter</a> for travel tips, inspiration, and photos from around the world.</em></p>",
      "short": "You won't see a car driving down Playa del Carmen's main thoroughfare, Quinta Avenida (or Fifth Avenue in English). Cars are off-limits here. Instead, live marimba musicians, pedestrians, fire-breathers, and vendors hawking handmade goods and Cuban cigars flood the cobblestone street. Less than a block from this lively main drag, the four-star Acanto Boutique Hotel puts you in prime position for exploring Playa del Carmen's Mayan architecture, checking out its hip nightlife, and kicking back on the Caribbean beaches that are just steps away."
  },
  "published_at": "2015-01-13T06:00:00Z",
  "urls": {
    "info": "http://www.groupon.com/deals/ga-acanto-boutique-hotel-9",
    "reviews": "http://www.tripadvisor.com/Hotel_Review-g150812-d535230-Reviews-Acanto_Boutique_Hotel-Playa_del_Carmen_Yucatan_Peninsula.html#REVIEWS",
    "purchase": "https://www.groupon.com/deals/ga-acanto-boutique-hotel-9/confirmation?pledge_id=12223065"
  },
  "images": {
    "thumbnail": {
      "url": "https://img.grouponcdn.com/deal/YYeRx1sMmgiooQoWUBu/Hv-960x582/v1/t50x50.jpg",
      "width": 50,
      "height": 50
    },
    "full_size": {
      "url": "https://img.grouponcdn.com/deal/YYeRx1sMmgiooQoWUBu/Hv-960x582/v1/t440x300.jpg",
      "width": 440,
      "height": 300
    },
    "other": []
  },
  "location": {
    "lat_lon": [
        20.6285958,
        -87.0695653
    ],
    "street_address": "  ",
    "city": "",
    "region_name": "",
    "zipcode": "",
    "country": "Mexico",
    "country_code": null,
    "woeid": null,
    "latitude": 20.6285958,
    "longitude": -87.0695653
  },
  "price": {
    "value": 599,
    "display_value": null,
    "comparison_value": null,
    "iso_code": null,
    "name": null,
    "symbol": null
  },
  "fine_print": "Must book by 3/13/15 or promotional value expires. Travel 1/18/15–3/31/15 or 4/1/15–8/31/15. Limit 1 per person, may buy 2 additional as gifts. Limit 1 per visit. Valid only for option purchased. Reservation required, subject to availability. 30-day cancellation notice required or fee up to the Groupon price applies. Must be 21+ to check in. Credit card required at booking and check-in. Must use promotional value in 1 visit. Not valid with reward points. $250 refundable credit card authorization required as security deposit at check-in. 19% tax not included.\n",
  "merchant": {
    "name": "Acanto Boutique Hotel",
    "phone_number": "888-331-2177",
    "url": "http://www.acantohotels.com/"
  },
  "source": {
    "id": null,
    "name": null,
    "description": null,
    "url": null,
    "icon": {
      "url": null,
      "width": null,
      "height": null
    }
  },
  "origin": {
    "id": "ga-acanto-boutique-hotel-9",
    "name": "Groupon Getaway",
    "url": "http://www.groupon.com/deals/ga-acanto-boutique-hotel-9",
    "icon": {
      "url": "http://images-backstitch.s3.amazonaws.com/next/service_catalog/groupon_icon.png",
      "width": "16",
      "height": "16"
    }
  }
}

A place that offers paid lodging.

Field Data Type Description
id string A unique identifier for the result
type string The type of the result
title object Contains both a short and long hotel name
description object Contains both a short and long hotel description
published_at string The date that this hotel was originally published in UTC
urls object Direct links to hotel information, reviews, and direct purchasing
images array A list of hotel images
location object If available the geolocation of where the hotel is available
price object The cost of the hotel
fine_print string If available any additional fine-print details
merchant object If available the name the hotel, their phone number, and the url of their website
source object If available details about the user that posted this hotel
origin object Details about the website that is selling lodging at this hotel