Twitter - Search

Declaration

<AMTWITTER ACTIVITY="search" RESULTDATASET="text" SCREENNAME="text" ACCESSTOKEN="text" SECRETTOKEN="text">text<Parameter Name="text" Value="text" /></AMTWITTER>

See Also

Twitter - Delete Status | Twitter - Follow User | Twitter - Get Direct Messages | Twitter - Get Followers | Twitter - Get Friends | Twitter - Get Mentions | Twitter - Get Status | Twitter - Get Timeline | Twitter - Send Direct Messages | Twitter - Stop Following User | Twitter - Update Status

Description

Creates a saved search for the authenticated user based on a search query. Results are saved to a dataset. This activity supports the use of optional parameters enabling more advanced searches to be implemented.

IMPORTANT: Use of this activity requires a valid Twitter account.

Practical Usage

Mainly returns tweets that match a specified query and populates a dataset with the results.

Parameters

General Properties

Property

Type

Required

Default

Markup

Description

Query

Text

Yes

(Empty)

....>SearchText</AMTWITTER>

The search query to execute. This parameter supports most search operators which can be typed directly into the search box. Valid search operators are listed below under Notes.

Create and populate dataset with user information

Text

Yes

(Empty)

RESULTDATASET="theDataset"

The name of the dataset to create and populate with information resulting from the specified query. More on the dataset that this activity creates can be found under Notes below.  

Authentication Properties

Property

Type

Required

Default

Markup

Description

Default Keys

 

 

 

 

If enabled, specifies that the default consumer/secret key combination used to authorize AutoMate access to Twitter API will be used. This also determines the text status that appears via Twitter application. Selecting this option would show AutoMate as the default application used to perform status updates. This is a visual mode parameter used only during design time, therefore, contains no markup. If this parameter is enabled, the Custom Keys parameter is ignored. It is enabled by default.

Custom Keys

 

 

 

 

If enabled, specifies that a custom consumer/secret key combination should be entered. This also determines the text status that appears via Twitter application. Selecting this option would show the specified application name as the one used to perform status updates. This is a visual mode parameter used only during design time, therefore, contains no markup. If this parameter is enabled, the Default Keys parameter is ignored.

Consumer Key

Text

No

(Empty)

CONSUMERKEY="text"

The consumer key to authenticate with. To use the Twitter API, each client application you register will be provisioned a consumer key and secret. This parameter is available only if the Custom Keys parameter is enabled. More information about OAuth authentication can be found below under Notes.  

Consumer Secret

Text

No

(Empty)

CONSUMERSECRET="encrypted"

The consumer key secret to authenticate with. To use the Twitter API, each client application you register will be provisioned a consumer key and secret. This parameter is available only if the Custom Keys parameter is enabled. More information about OAuth authentication can be found below under Notes.

Get PIN

 

 

 

 

You must initially register AutoMate (or the desired application) to allow it to use the Twitter API. If you have not done so already, click the Get Pin button. This will open your Twitter account site. Follow the instructions and copy the provided pin. Thereafter, return to the AutoMate Twitter authentication properties dialog and paste it in the Pin text box. Click the Authenticate Pin button to produce a consumer key and secret, thus, completing the token exchange. This is a visual mode parameter used only during design time, therefore, contains no markup.

NOTE: This is a one-time process. Once authenticated, the information will be stored on your system. More information about OAuth authentication can be found below under Notes.    

Pin

 

 

 

 

The pin in which to authorize AutoMate to allow it to use the Twitter API. This is a visual mode parameter used only during design time, therefore, contains no markup.

Authenticate Pin

 

 

 

 

Click this button to authenticate the provided PIN. This is a visual mode parameter used only during design time, therefore, contains no markup.  

NOTE: This is a one-time process. Once authenticated, the information will be stored on your system.

Screen Name

Text

Yes

(Empty)

SCREENNAME="Catwoman"

The screen name of the authenticating user. This is a visual mode parameter used only during design time, therefore, contains no markup.

Enable SSL

Yes/No

No

(Empty)

ENABLESSL="yes"

If set to YES, SSL is enabled. This parameter is set to NO by default.

Access Token

Text

No

(Empty)

SECRETTOKEN="encrypted"

The Oauth Access Token. This allows OAuth applications to directly exchange Twitter user names and passwords for OAuth access tokens and secrets. More information can be found below under Notes.  

Access Token Secret

Text

No

(Empty)

SECRETTOKEN="text"

The Oauth Token Secret. This allows OAuth applications to directly exchange Twitter user names and passwords for OAuth access tokens and secrets. More information can be found below under Notes.  

Parameters Properties

This activity allows you to set name/value parameters to filter results. The parameter names that this activity allows are listed below under Notes.

Property

Type

Required

Default

Markup

Description

Name

Text

No

(Empty)

Name="page"

The parameter name.

Value

Number

No

(Empty)

Value="3"

The value associated to the parameter.

Proxy Properties (Only HTTP proxy OS supported)

Property

Type

Required

Default

Markup

Description

Proxy Host

Text

No

(Empty)

PROXYSERVER="host.domain.com"

The host name (i.e. server.domain.com) or IP address  (i.e. xxx.xxx.xxx.xxx) of the proxy server.

Proxy Port

Number

No

(Empty)

PROXYPORT="300"

The port that should be used to connect.

Proxy Username

Text

No

(Empty)

PROXYUSERNAME="user"

The user name that should be used to authenticate when connecting through the proxy server.

Proxy Password

Text

No

(Empty)

PROXYPASSWORD="encrypted"

The password that should be used to authenticate when connecting through the proxy server.

Description Properties

The Description tab allows you to customize the text description of any step as it appears in the Task Builder's Steps Pane.

More on setting custom step description

Error Causes Properties

The Error Causes tab allows you to select/omit specific errors that should cause a particular step to fail.

More on Error Causes properties

On Error Properties

The On Error tab allows you to determine what the task should do if a particular step encounters an error.

More about On Error properties

Notes

OAuth Consumer Key/Secret Authentication

To use the Twitter API, the first thing you have to do is register a client application. Each client application you register will be provisioned a consumer key and secret. This key and secret scheme is similar to the public and private keys used in protocols such as ssh for those who are familiar. This key and secret will be used, in conjunction with an OAuth library in your programming language of choice, to sign every request you make to the API. It is through this signing process that Twitter trusts that the traffic that identifies itself is in fact you.

OAuth authentication is the process in which Users grant access to their Protected Resources without sharing their credentials with the Consumer. OAuth uses Tokens generated by the Service Provider instead of the User’s credentials in Protected Resources requests. The process uses two Token types:

Request Token:

Used by the Consumer to ask the User to authorize access to the Protected Resources. The User-authorized Request Token is exchanged for an Access Token, MUST only be used once, and MUST NOT be used for any other purpose. It is RECOMMENDED that Request Tokens have a limited lifetime.

Access Token:

Used by the Consumer to access the Protected Resources on behalf of the User. Access Tokens MAY limit access to certain Protected Resources, and MAY have a limited lifetime. Service Providers SHOULD allow Users to revoke Access Tokens. Only the Access Token SHALL be used to access the Protect Resources.

OAuth Authentication is done in three steps:

  1. The Consumer obtains an unauthorized Request Token.

  2. The User authorizes the Request Token.

  3. The Consumer exchanges the Request Token for an Access Token.

Datasets

A dataset is a multiple column, multiple row container object. This activity creates and populates a dataset containing a specific set of fields. The table below describes these fields (assuming the dataset name assigned is theDataset).

Name

Type

Return Value

theDataset.Created

Date

The timestamp of element creation, either status or user. (Example: Sat Jan 24 22:14:29 +0000 2009)

theDataset.ID

Number

The unique ID Twitter assigned for the user. (Examples: 14597523)

theDataset.FromUser

Number

The user who sent the status.

theDataset.ToUser

Text

The user who received the status.

theDataset.Source

Text

The name of the application that sent the status.

theDataset.Text

Text

The escaped and HTML encoded status body. (Examples: I am eating oatmeal, The first tag is always <html>)

Parameters

Name

Type

Description

lang

Text

Restricts tweets to the given language.

locale

Text

Specify the language of the query you are sending (only ja is currently effective). This is intended for language-specific clients and the default should work in the majority of cases.

rpp

Number

The number of tweets to return per page, up to a max of 100.

page

Number

The page number (starting at 1) to return, up to a max of roughly 1500 results

since_id

Text

Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occurred since the since_id, the since_id will be forced to the oldest ID available.

until

Date

Returns tweets generated before the given date. Date should be formatted as YYYY-MM-DD.

geocode

Text

Returns tweets by users located within a given radius of the given latitude/longitude. The location is preferentially taking from the Geotagging API, but will fall back to their Twitter profile. The parameter value is specified by "latitude,longitude,radius", where radius units must be specified as either "mi" (miles) or "km" (kilometers). Note that you cannot use the near operator via the API to geocode arbitrary locations; however you can use this geocode parameter to search near geocodes directly.

show_user

True/False

When true, prepends ":" to the beginning of the tweet. This is useful for readers that do not display Atom's author field. The default is false.

result_type

Text (options)

Specifies what type of search results you would prefer to receive. The current default is mixed. Valid values include:

  • mixed: Include both popular and real time results in the response.

  • recent: return only the most recent results in the response

  • popular: return only the most popular results in the response.

Operators

You can enter these search operators directly into the Query text box (operators are marked red).

Operator

Find Tweets.....

twitter search

containing both "twitter" and "search". This is the default operator.

"happy hour"

containing the exact phrase "happy hour".

love OR hate

containing either "love" or "hate" (or both).

beer -root

containing "beer" but not "root".

#haiku

containing the hashtag "haiku".

from:alexiskold

sent from person "alexiskold".

to:techcrunch

sent to person "techcrunch".

@mashable

referencing person "mashable".

"happy hour" near:"san francisco"

containing the exact phrase "happy hour" and sent near "san francisco".

near:NYC within:15mi

sent within 15 miles of "NYC".

superhero since:2010-09-09

containing "superhero" and sent since date "2010-09-09" (year-month-day).

ftw until:2010-09-09

containing "ftw" and sent up to date "2010-09-09".

movie -scary :)

containing "movie", but not "scary", and with a positive attitude.

flight :(

containing "flight" and with a negative attitude.

traffic ?

containing "traffic" and asking a question.

hilarious filter:links

containing "hilarious" and linking to URLs.

news source:twitterfeed

containing "news" and entered via TwitterFeed.

Variables and Expressions

All text fields allow the use of expressions, which can be entered by surrounding the expression in percentage signs (Example: %myVariable% or %Left('Text',2)%). To help construct these expressions, you can open Expression Builder from these fields by clicking the Insert expression/variable button or pressing F2.

More on variables
More on expressions

More on the Expression Builder

Example

NOTE: The code below can be copied and pasted directly into the Steps pane of the Task Builder.

 

Description: This sample step returns tweets containing either the text "love" or "hate" (or both) and were generated before 2010-01-01. Status information is populated into an AutoMate dataset named "theDataset".

 

<AMTWITTER ACTIVITY="search" RESULTDATASET="theDataset" SCREENNAME="ronneylovely" ACCESSTOKEN="133348295-PORXRI8G89z6oQBklBYE8JN98VffugsRPAsnEKtw" SECRETTOKEN="DtemBbytOZERrkUBYFagHV1e5jju1APQ5cMo1GCMU">love OR hate<Parameter Name="until" Value="2010-01-01" /></AMTWITTER>

 

↑ Top of Page