Twitter - Search
Declaration
<AMTWITTER ACTIVITY="search" CONSUMERKEY="text" CONSUMERSECRET="text (encrypted)" SCREENNAME="text" ACCESSTOKEN="text" SECRETTOKEN="text (encrypted)" ENABLESSL="YES/NO" PROXYTYPE="text (options)" PROXYSERVER="text" PROXYPORT="number" PROXYUSERNAME="text" PROXYPASSWORD="text (encrypted)" QUERY="text" RESULTDATASET="text" >text<PARAMETER NAME="text (options)" VALUE="text" /></AMTWITTER>
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.
Practical usage
Mainly returns tweets that match a specified query and populates a dataset with the results.
Parameters
Authentication
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| Type | --- | --- | --- | --- | Specifies
the type of authentication that should be used to establish a
Twitter connection. The available
options are:
NOTE: This parameter does not contain markup and is only displayed in visual mode for task construction and configuration purposes. |
| Consumer key | Text | Yes, if Type is set to Custom keys | (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. |
| Consumer secret | Text | Yes, if Type is set to Custom keys | (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. |
| Get PIN | --- | --- | --- | --- | You
must initially register Automate Desktop (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 Desktop
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.
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 OAuth
Consumer Key/Secret Authentication. |
| Pin | --- | --- | --- | --- | The
pin in which to authorize Automate Desktop to allow it to use the Twitter
API. NOTE: This parameter does not contain markup and is only displayed in visual mode for task construction and configuration purposes. |
| 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. NOTE: This parameter does not contain markup and is only displayed in visual mode for task construction and configuration purposes. |
| Enable SSL | Yes/No | No | (Empty) | ENABLESSL="yes" | If selected, SSL is enabled. This parameter is disabled by default. |
| Access token | Text | No | (Empty) | SECRETTOKEN="pL1IdTedxHU6JFd6HHRlknM" | 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 OAuth Consumer Key/Secret Authentication. |
| 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 OAuth Consumer Key/Secret Authentication. |
Proxy
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| Proxy type | Text (options) | Yes | Default |
|
The
type of proxy required for connections that pass through
a proxy server. The available options are:
|
| Use authentication | --- | No | --- | --- | If
enabled, specifies proxy authentication is required,
enabling authentication-based parameters (disabled by default).
It is active only if Proxy
type is set to HTTP. NOTE: This parameter does not contain markup and is only displayed in visual mode for task construction and configuration purposes. |
| Proxy server | Text | No | (Empty) | PROXYSERVER="proxy.host.com" | The hostname (server.domain.com) or IP address (xxx.xxx.xxx.xxx) of the proxy server. This parameter is available only if Proxy type is set to HTTP. |
| Proxy username | Text | No | (Empty) | PROXYUSERNAME="username" | The proxy username to authenticate with. This parameter is available only if Use authentication is enabled. |
| Proxy port | Number | No | 808 | PROXYPORT="8080" | The port number to use to connect to the proxy server. This parameter is available only if Proxy type is set to HTTP. The default value is 808. |
| Proxy password | Text | No | (Empty) | PROXYPASSWORD="encrypted" | The proxy password to authenticate with. This parameter is available only if Use Authentication is enabled. |
General
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| Query | Text | Yes | (Empty) | QUERY="#haiku" | 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 Operators. |
| 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. For more information, see Datasets. |
Parameters
This activity allows you to set name/value parameters to filter results. The parameter names that this activity allows are listed below under Parameters.
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| Name | Text | No | (Empty) | NAME="page" | The parameter name. |
| Value | Number | No | (Empty) | VALUE="3" | The parameter value. |
Additional 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:
-
The Consumer obtains an unauthorized Request Token.
-
The User authorizes the Request Token.
-
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 was 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 | 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 by way of 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:
|
Operators
You can enter these search operators directly into the Query text box (operators are in bold).
| 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 by way of 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 theInsert expression/variablebutton or pressingF2.
More on variables
More on expressions
More on the Expression Builder
Examples
- Copy and paste the sample AML code below directly into the Task Builder Steps Panel.
- To successfully run the sample code, update parameters containing user credentials, files, file paths, or other information specific to the task to match your environment.
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 Desktop 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>