1\name{searchTwitter}
2\alias{searchTwitter}
3\alias{Rtweets}
4\alias{searchTwitteR}
5\title{ Search twitter }
6\description{
7  This function will issue a search of Twitter based on a supplied
8  search string.
9}
10\usage{
11searchTwitter(searchString, n=25, lang=NULL, since=NULL, until=NULL,
12              locale=NULL, geocode=NULL, sinceID=NULL, maxID=NULL,
13	      resultType=NULL, retryOnRateLimit=120, ...)
14Rtweets(n=25, lang=NULL, since=NULL, ...)
15}
16\arguments{
17  \item{searchString}{Search query to issue to twitter. Use "+" to separate query terms.}
18  \item{n}{The maximum number of tweets to return}
19  \item{lang}{If not \code{NULL}, restricts tweets to the given
20    language, given by an ISO 639-1 code}
21  \item{since}{If not \code{NULL}, restricts tweets to those since the
22    given date.  Date is to be formatted as YYYY-MM-DD}
23  \item{until}{If not \code{NULL}, restricts tweets to those up until the
24    given date.  Date is to be formatted as YYYY-MM-DD}
25  \item{locale}{If not \code{NULL}, will set the locale for the search.
26    As of 03/06/11 only \code{ja} is effective, as per the Twitter API}
27  \item{geocode}{If not \code{NULL}, returns tweets by users located
28    within a given radius of the given latitude/longitude. See
29    \code{Details} below for more information}
30  \item{sinceID}{If not \code{NULL}, returns tweets with IDs greater
31    (ie newer) than the specified ID}
32  \item{maxID}{If not \code{NULL}, returns tweets with IDs smaller
33    (ie older) than the specified ID}
34  \item{resultType}{If not \code{NULL}, returns filtered tweets as per value.
35    See details for allowed values.}
36  \item{retryOnRateLimit}{If non-zero the search command will block retry up to
37    X times if the rate limit is experienced. This might lead to a much longer run
38    time but the task will eventually complete if the retry count is high enough}
39  \item{...}{Optional arguments to be passed to \code{\link{GET}}}
40}
41\details{
42  These commands will return any authorized tweets which match the
43  search criteria.  Note that there are pagination restrictions as well
44  as other limits on what can be searched, so it is always possible to
45  not retrieve as many tweets as was requested with the \code{n}
46  argument.  Authorized tweets are public tweets as well as those
47  protected tweets that are available to the user after authenticating
48  via \code{\link{registerTwitterOAuth}}.
49
50  The \code{searchString} is always required. Terms can contain spaces,
51  and multiple terms should be separated with "+".
52
53  For the \code{geocode} argument, the values are given in the format
54  \code{latitude,longitude,radius}, where the radius can have either
55  \code{mi} (miles) or \code{km} (kilometers) as a unit.  For example
56  \code{geocode='37.781157,-122.39720,1mi'}.
57
58  For the \code{sinceID} argument, if the requested ID value is older
59  than the oldest available tweets, the API will return tweets starting
60  from the oldest ID available.
61
62  For the \code{maxID} argument, tweets upto this ID value will be returned
63  starting from the oldest ID available. Useful for paging.
64
65  The \code{resultType} argument specifies the type of search results received
66  in API response. Default is \code{mixed}.
67  Allowed values are \code{mixed} (includes popular + real time results),
68  \code{recent} (returns the most recent results) and \code{popular}
69  (returns only the most popular results).
70
71  The \code{Rtweets} function is a wrapper around \code{searchTwitter}
72  which hardcodes in a search for \code{#rstats}.
73}
74\value{
75  A list of \code{\link{status}} objects
76}
77\author{Jeff Gentry}
78\seealso{ \code{\link{status}}}
79\examples{
80  \dontrun{
81  	searchTwitter("#beer", n=100)
82          Rtweets(n=37)
83
84  	## Search between two dates
85          searchTwitter('charlie sheen', since='2011-03-01', until='2011-03-02')
86
87  	## geocoded results
88  	searchTwitter('patriots', geocode='42.375,-71.1061111,10mi')
89
90    ## using resultType
91    searchTwitter('world cup+brazil', resultType="popular", n=15)
92    searchTwitter('from:hadleywickham', resultType="recent", n=10)
93
94  }
95}
96\keyword{ interface }
97