Intro

https://needtagger.3scale.net/#how-it-works

Sign in | Sign up

Intro

API Docs

Get a Key

Forum

Help

3Scale Help

Social Signals API

Mine your social data for commercial intent, in real time.

Contents
Overview
Uses
Social Signals (tags)
How We Identify Intent
Preparing Your Data
Using The API
Building Custom Signals
Limitations
Response Codes
Data Sources
Precision and Recall

Overview
Social Signals API provides programmatic access to the intent-mining platform that thousands of NeedTagger customers use to mine
Twitter for people who need their products, services and assistance, right now.
Our API identifies over 70 types of commercial intent in short-form user-generated text like the kind found on the most popular social
networks. While optimized for Twitter, it also classifies Facebook posts, LinkedIn messages, blog comments, forum posts and other
short-form text messages.
Note: Social Signals API is a data processing (classification) service, not a source of social data. We do not resell or distribute tweets. It
processes social data supplied by you and returns insights in the form of document IDs and "intent tags".
How does Social Signals differ from other text analytics APIs (Clarabridge, NetBase, OpenAmplify, Alchemy, et al)?
Social Signals differs from traditional text analytics APIs in several ways:
We surface actionable signals of intent: Instead of classifying text for sentiment, "leads", action phrases or parts of speech,
Social Signals identifies specific types of commercially relevant events ("I just got promoted") and purchase intent ("I need a new
car") that any marketer can take advantage of without further processing.
We analyze more than text: our platform and applications can analyze more data than the body of the message to classify intent.
As a result, our precision and recall (for classifying intent) are best-in-class.
We identify implied needs, too (for products and services): in addition to explicit statements of need ("Looking for a new crib"),
our pre-engineered tags identify root causes of the need ("we're pregnant!").
Easy to customize: you can create your own custom Social Signals (classification filters) for any business niche, task or
application using our self-service NeedTagger app. No PhDs, consultants or machine training are required. NOTE: location and
profile settings will not carry-over into this API.
Real-time results: social data is classified in seconds.
Preview signal quality before committing to production: Using our self-service NeedTagger app, edit and test signals against
Twitter's fire hose as often as you like. Results are presented in real-time.
What types of "social signals" does the API find?
The API identifies four types of commercial intent in a social media post. One of these, Life Events, is still in beta.
1. Type of Need ("Intent:"). The general intention of the post without regard to a topic. Examples: Asking Questions, Complaining,
Requesting Help, Scheduling and Searching.
2. Product & Service Needs ("Product:"). A need expressed for one (or more) of 60 common product and service categories, for
example: a new car, pain medication, marketing software or legal services.
3. Life Events ("LifeEvent:" IN BETA). Important events in a persons life such as getting married, changing jobs and moving to a
new city. Life events are useful in developing a brand strategy, planning advertising campaigns and for market research. Marketing
directly to life events is also an important way of selling big-ticket items such as insurance and real estate.
4. Custom Social Signals you create ("Other:"): You may create your own custom social signals using NeedTagger's self-service
customer prospecting app, which is available online at app.needtagger.com. Most custom signal filters match a Type of Need
with discussion topics/keywords, for example, 'Asking Questions' about 'security software'.
What percent of my social data will contain commercial intent?
It depends on the data you submit for processing. If you submit data that has been pre-filtered for commercial topics (brands, products,
keywords) then you should expect 10% to 40% of the posts to include some form of intent. If your posts are not pre-filtered by topic,
then the yield will probably be less than 10%.

Uses
Business applications of Social Signals include:

1 of 6

7/18/13 2:06 PM

Intro

https://needtagger.3scale.net/#how-it-works

Social Sales Prospecting: identify new leads and potential customers expressing needs for your type of product/service.
Lead Nurturing: use Social Signals to trigger lead-nurturing emails to contacts in your Marketing Automation or CRM database.
Customer Support: surface complaints, questions and requests for help related to your business, brands, products and people.
Content Marketing: identify people requesting or needing content you've already produced.
Behavioral Analytics: understand the intentions and behaviors of an audience.
Real-Time Marketing Triggers: automatically trigger emails, score leads and send alerts in response to a person's social media
behavior.
To accomplish the above, Social Signals can be fed into Marketing Automation, CRM, Customer Support and Social Media
Monitoring/Analytics applications as depicted in the graphic below.

Social Signals (tags)

What signals (tags) will I receive from the API?
NeedTagger identifies up to 4 types of intent signals in every social media post submitted to it.
NOTE: If you don't see what you need below, you may create a Custom signal using our self-service NeedTagger app. Or, contact us to
build a custom signal for you (for a fee).
1. Type of Need ("Intent:"):
The general type(s) of intent conveyed by the post:
Applying or Registering (useful in Education vertical)
Asking Questions
Betting
Buying
Complaining
Hungry (useful for Food Services vertical)
Just Arrived (useful for Travel vertical)
Moving
Needing
Repair Needed
Requesting Help
Scheduling or Planning
Searching for
Wishing or Wanting (aspirational)
2. Product and Service Needs ("Product:"):
The intent to purchase a specific type of product or service.
air travel
applying for college
baby products
beachwear
burgers
car repair
chicken
Chinese food
college
compact car
computer repair
content management software
CRM software
database technology
dentist
digital camera
environment friendly products
family sedan
fast food
French food

2 of 6

7/18/13 2:06 PM

Intro

https://needtagger.3scale.net/#how-it-works

Greek food
hair salon
haircut
home appliance
home mortgage
immigration issue
insurance
Italian food
Japanese food
landed at an airport
LASIK surgery
legal issue
losing weight
marketing automation software
Mexican food
new computer
new mobile phone
pizza
plastic surgery
pregnancy
rental car
retirement facility
search engine optimization
social media followers
social media monitoring software
suffering from allergies
suffering from headache
suffering from insomnia
suffering from pain
suffering from stomach problem
SUV
tablet devices
teeth whitening
Thai food
truck
used car
vehicle any type
web servers
windshield repair
3. Life Events ("LifeEvent:" IN BETA):
Commercially significant events occurring in the author's life.
legal issues
pregnancy
major mortgage
losing or gaining weight
change in residence
change in schools
change in job
recently hired
recently promoted
lost job
seeking a job
+ more in development
4. Custom Social Signals you create ("Other :") - OPTIONAL:
You may create custom social signals using NeedTagger's self-service customer prospecting app, which is available online at
app.needtagger.com.. Your stream name will be returned as the tag.

How We Identify Intent

NeedTagger uses a combination of thoroughly-tested language patterns and proprietary multi-variate algorithms to classify intent. We
build & test our algorithms using a mix of machine & human analysis. Many of our pre-engineered filters detect implied needs and root
causes (I just injured my knee!) in addition to explicit signals (dammit, I need an MRI).
At this time, the Social Signals API analyzes the body of a post. However, our platform can analyze many more types of data to
determine intent. This is how our NeedTagger application works. Other variables considered by our platform include: the context of the
conversation, the authors profile, the conversational style, the location of the post and the author, whether content sharing is involved
and more.We plan to expose this additional level of intelligence in future releases.

Preparing Your Data

Data submitted to the API should adhere to the following guidelines:
1. Minimum required data per post: every document submitted should contain at least two fields:
content: the body of the post (text)
id: a unique identifier for each document you submit (text)
2. English language only: our API does not classify non-English posts. No results will be returned for non-English posts (we filter-out
non English posts before processing).

3 of 6

7/18/13 2:06 PM

Intro

https://needtagger.3scale.net/#how-it-works

3. Less than 400 characters per post: posts over 400 characters may generate poor results.
4. No more than 100 posts per call: submissions containing more than 100 posts will provide results for the first 100 posts only.
The remaining posts will not be classified, and no error will be generated.
5. You will need to filter for location and profiles separately: location and profile settings made in NeedTagger's app will not
carry-over into Social Signals API filters.

Using the API

See our active API Docs to learn about our methods.
After you register your application and obtain your API Key, signup for a NeedTagger account (Free) at app.needtagger.com . Then,
contact us at support@needtagger.com to obtain your NeedTagger Access Token, which you will place into every API call. In your email,
please provide us with the email address you use as your NeedTagger login ID.
Social media documents should be submitted to the API in a JSON format (see example below). Your NeedTagger Access Token is
required with each submission, as shown below.

There are three rate-engineered API methods available to support from 1 to 100 documents per call. No more than 100 documents can
be processed per API call, so larger submissions should be divided into 100-document packages.
Here is an example of social data formatted correctly for processing (required fields marked with an asterisk *):

For each document (post) processed through the API, a set of intent tags will be returned. These tags are human-readable. Many will
be empty, indicating that no intent was detected.
Here is what a Social Signals API result looks like (JSON format):

The API will return as many social signals (tags) as it finds in each post (see lists above), PLUS tags for custom streams that the owner of
the API key has created using their NeedTagger account (web or HootSuite app).
API results are returned within seconds of receiving the data submission.

Custom Signals
How do I create custom Social Signals for my business?
After obtaining your User Token and API key, there are 5 steps involved:
1. If you don't already have one, create a Free NeedTagger account (takes 3 minutes).
2. Create an intent-filtered Twitter stream in the NeedTagger app (free) and give it a short name. In the app you can preview & tweak
the results of your custom signal filter in real-time, against the Twitter firehose. When you are happy with the filter quality, save your
stream.
3. Update the Social Signals API database with your latest Custom signal definitions by calling the /synchronize method. See API
Docs for an example.
4. Now you are ready to use your Custom signals. Post your social data to the NeedTagger API and receive results in seconds. Your
Custom signal tags will appear in your results as, "Other:your stream name".
5. Use your social signals in your application.

4 of 6

7/18/13 2:06 PM

Intro

https://needtagger.3scale.net/#how-it-works

Limitations
Although NeedTaggers API will work fine with any type of short-form social media posts, it is optimized for Twitter.
The API processes English language posts only.

Response Codes
Over Limit Error
1. Response Code* 409
2. Response Body Limits exceeded
Authentication Failed Error
1. Response Code* 403
2. Response Body Authentication failed
Authentication Missing Error
1. Response Code* 403
2. Response Body Authentication parameters missing
No Match Error
1. Response Code* 404
2. Response Body No rule matched

Data Sources
Social Signals API is optimized to analyze posts containing less than 400 characters of text. This covers: 100% of Twitter posts; 90% of
Facebook posts and comments; most blog comments (but not full blog posts); most comments posted to community forums such as
discussion groups and fan pages.

Precision and Recall

In internal tests we have seen the following precision and recall figures. These numbers are for English-language posts from Twitter that
were pre-filtered for brands and products prior to submission to the Social Signals API. Posts from other social networks will score
slghtly lower, on average.
Type of Intent ("Intent:"): Precision: 70-95% Recall: 80-90%
Products and Services ("Product:") & Life Events ("LifeEvent:"): Precision: 65-90% Recall: 70-90%
Custom Social Signals ("Other:"): precision and recall will depend upon the user's configuration of custom signal filters.
For example, here are the test results from a May, 2013, internal analysis of 1,000 topic-filtered tweets in the fast food, travel and
automotive industries:

5 of 6

7/18/13 2:06 PM

Intro

https://needtagger.3scale.net/#how-it-works

NOTE: All precision and recall numbers are calculated by comparing automated classification results against human-classified "gold
standard" using the same data. Because human opinion enters into this definition, precision and recall statistics can only be used as a
guideline. Your interpretation may vary.
2013

6 of 6

7/18/13 2:06 PM