1 | # Twitter for Node.js
|
2 |
|
3 | An asynchronous client library for the Twitter [REST](https://dev.twitter.com/rest/public) and [Streaming](https://dev.twitter.com/streaming/overview) API's.
|
4 |
|
5 | [![wercker status](https://app.wercker.com/status/624dbe8ad011852d1e01d7dc03941fc5/s/master "wercker status")](https://app.wercker.com/project/bykey/624dbe8ad011852d1e01d7dc03941fc5) [![NPM](https://nodei.co/npm/twitter.png?mini=true)](https://nodei.co/npm/twitter/)
|
6 |
|
7 | ```javascript
|
8 | var Twitter = require('twitter');
|
9 |
|
10 | var client = new Twitter({
|
11 | consumer_key: '',
|
12 | consumer_secret: '',
|
13 | access_token_key: '',
|
14 | access_token_secret: ''
|
15 | });
|
16 |
|
17 | var params = {screen_name: 'nodejs'};
|
18 | client.get('statuses/user_timeline', params, function(error, tweets, response) {
|
19 | if (!error) {
|
20 | console.log(tweets);
|
21 | }
|
22 | });
|
23 | ```
|
24 |
|
25 | ## Installation
|
26 |
|
27 | `npm install twitter`
|
28 |
|
29 | ## Quick Start
|
30 |
|
31 | You will need valid Twitter developer credentials in the form of a set of consumer and access tokens/keys. You can get these [here](https://apps.twitter.com/). Do not forgot to adjust your permissions - most POST request require write permissions.
|
32 |
|
33 | ```javascript
|
34 | var Twitter = require('twitter');
|
35 | ```
|
36 |
|
37 | ## For User based authentication:
|
38 |
|
39 | ```javascript
|
40 | var client = new Twitter({
|
41 | consumer_key: '',
|
42 | consumer_secret: '',
|
43 | access_token_key: '',
|
44 | access_token_secret: ''
|
45 | });
|
46 | ```
|
47 |
|
48 | Add your credentials accordingly. I would use environment variables to keep your private info safe. So something like:
|
49 |
|
50 | ```javascript
|
51 | var client = new Twitter({
|
52 | consumer_key: process.env.TWITTER_CONSUMER_KEY,
|
53 | consumer_secret: process.env.TWITTER_CONSUMER_SECRET,
|
54 | access_token_key: process.env.TWITTER_ACCESS_TOKEN_KEY,
|
55 | access_token_secret: process.env.TWITTER_ACCESS_TOKEN_SECRET
|
56 | });
|
57 | ```
|
58 | ## For Application Only based authentication:
|
59 |
|
60 | You will need to fetch a bearer token from Twitter as documented [Here](https://dev.twitter.com/oauth/application-only), once you have it you can use it as follows.
|
61 |
|
62 | ```javascript
|
63 | var client = new Twitter({
|
64 | consumer_key: '',
|
65 | consumer_secret: '',
|
66 | bearer_token: ''
|
67 | });
|
68 | ```
|
69 |
|
70 | Add your credentials accordingly. I would use environment variables to keep your private info safe. So something like:
|
71 |
|
72 | ```javascript
|
73 | var client = new Twitter({
|
74 | consumer_key: process.env.TWITTER_CONSUMER_KEY,
|
75 | consumer_secret: process.env.TWITTER_CONSUMER_SECRET,
|
76 | bearer_token: process.env.TWITTER_BEARER_TOKEN
|
77 | });
|
78 | ```
|
79 |
|
80 | NB - You will not have access to all endpoints whilst using Application Only authentication, but you will have access to higher API limits.
|
81 |
|
82 | ## Requests
|
83 |
|
84 | You now have the ability to make GET and POST requests against the API via the convenience methods.
|
85 |
|
86 | ```javascript
|
87 | client.get(path, params, callback);
|
88 | client.post(path, params, callback);
|
89 | client.stream(path, params, callback);
|
90 | ```
|
91 |
|
92 | ## REST API
|
93 |
|
94 | You simply need to pass the endpoint and parameters to one of convenience methods. Take a look at the [documentation site](https://dev.twitter.com/rest/public) to reference available endpoints.
|
95 |
|
96 | Example, lets get a [list of favorites](https://dev.twitter.com/rest/reference/get/favorites/list):
|
97 |
|
98 | ```javascript
|
99 | client.get('favorites/list', function(error, tweets, response) {
|
100 | if(error) throw error;
|
101 | console.log(tweets); // The favorites.
|
102 | console.log(response); // Raw response object.
|
103 | });
|
104 | ```
|
105 |
|
106 | How about an example that passes parameters? Let's [tweet something](https://dev.twitter.com/rest/reference/post/statuses/update):
|
107 |
|
108 | ```javascript
|
109 | client.post('statuses/update', {status: 'I Love Twitter'}, function(error, tweet, response) {
|
110 | if(error) throw error;
|
111 | console.log(tweet); // Tweet body.
|
112 | console.log(response); // Raw response object.
|
113 | });
|
114 | ```
|
115 |
|
116 | ## Streaming API
|
117 |
|
118 | Using the `stream` convenience method, you to open and manipulate data via a stream piped directly from one of the streaming API's. Let's see who is talking about javascript:
|
119 |
|
120 | ```javascript
|
121 | var stream = client.stream('statuses/filter', {track: 'javascript'});
|
122 | stream.on('data', function(event) {
|
123 | console.log(event && event.text);
|
124 | });
|
125 |
|
126 | stream.on('error', function(error) {
|
127 | throw error;
|
128 | });
|
129 |
|
130 | // You can also get the stream in a callback if you prefer.
|
131 | client.stream('statuses/filter', {track: 'javascript'}, function(stream) {
|
132 | stream.on('data', function(event) {
|
133 | console.log(event && event.text);
|
134 | });
|
135 |
|
136 | stream.on('error', function(error) {
|
137 | throw error;
|
138 | });
|
139 | });
|
140 | ```
|
141 |
|
142 | **Note** twitter stream several types of events, see [the docs](https://dev.twitter.com/streaming/overview/messages-types) for more info. There is no canonical way of detecting tweets versus other messages, but some users have had success with the following strategy.
|
143 |
|
144 | ```javascript
|
145 | _ = require('lodash')
|
146 | const isTweet = _.conforms({
|
147 | contributors: _.isObject,
|
148 | id_str: _.isString,
|
149 | text: _.isString,
|
150 | })
|
151 | ```
|
152 |
|
153 | ## Examples
|
154 |
|
155 | * [Tweet](https://github.com/desmondmorris/node-twitter/tree/master/examples#tweet)
|
156 | * [Search](https://github.com/desmondmorris/node-twitter/tree/master/examples#search)
|
157 | * [Streams](https://github.com/desmondmorris/node-twitter/tree/master/examples#streams)
|
158 | * [Proxy](https://github.com/desmondmorris/node-twitter/tree/master/examples#proxy)
|
159 | * [Media](https://github.com/desmondmorris/node-twitter/tree/master/examples#media)
|
160 |
|
161 | ## Contributors
|
162 |
|
163 | Originally authored by [@technoweenie](http://github.com/technoweenie)
|
164 | and maintained by [@jdub](http://github.com/jdub)
|
165 |
|
166 | Currently maintained by [@desmondmorris](http://github.com/desmondmorris)
|
167 |
|
168 | [And we cannot forget the community](https://github.com/desmondmorris/node-twitter/graphs/contributors)
|