hummingbird
Stupidly simple social media streaming for Node.js
Hummingbird is an independent node.js application that makes connecting to/managing real-time social media interactions simple. Real-time updates are processed by hummingbird and then placed into a Redis queue for whatever you want to do with them.
This README is only going to cover the basics for now, as the project is going through a bit of a refactor into new module.
Documentation is ongoing and incomplete, but you can get details in the wiki.
Supported Services
- Wordpress
Using Hummingbird
Hummingbird is manipulated strictly through a REST api, and each interaction must be defined by the service requesting a modification.
Accounts
Accounts for social media can be tracked my making REST calls to the /accounts
endpoint.
Supported by twitter, facebook, instagram
Create
POST /accounts
service=twitter
- (REQUIRED)service_id=123456789
- (REQUIRED) Must be the numerical ID of the twitter accountauth_token=sdfsdfsdf
- (facebook, instagram) Must be obtained by the oauth process of those services.
Destroy
DELETE /accounts
service=twitter
- (REQUIRED)service_id=123456789
- (REQUIRED) Must be the numerical ID of the twitter account
Keywords
Keywords are equivalent to hashtags without the hashtag, just the raw content. Supported by twitter, facebook, instagram.
Create
POST /keywords
service=twitter
- (REQUIRED)phrase=my keyword
- (REQUIRED) The phrase to track. Be sure to omit the "#" symbol.
Destroy
DELETE /keywords
service=twitter
- (REQUIRED)phrase=my keyword
- (REQUIRED) The phrase to track. Be sure to omit the "#" symbol.
Posts
When a real-time update is received, Hummingbird generates a post and stores it on your Redis queue.
Hummingbird posts normalize the updates into a single, consistent JSON format, regardless of the service it came from. Complete documentation on the structure of a post is available in the wiki.
Example Post
service: 'twitter' service_id: '123456790' // string, id of tweet timestamp: '2014-03-19T10:08:00.070Z' // string, ISO 8601 timestamp of tweet text: 'text @mention #keyword text' // string, tweet text content external_uri: 'http://service.com/service_id/status/123456790' // string, twitter tweet url author: service: 'twitter' service_id: '1234567890' // string, id of tweet author user_name: 'cool_dude23' // string, tweet author username display_name: 'Mr. Cool Dude' // string, tweet author formal name description: 'I am a cool dude.' // string, tweet author description avatar: 'http://service.com/1234567.jpg' // string, url to twitter user thumbnail mentions: service: 'twitter' service_id: '1234567' // string, id of mentioned account user_name: 'cool_dude23' // string, the username of mentioned account display_name: 'Mr. Cool Dude' // string, the formal name of the mentioned account keywords: phrase: 'chapmanu' // string, without #, of hashtags in tweet urls: domain: 'google.com' // string, the specific domain of the expanded URL link: 'http://google.com/news' // string, the full expanded url shortened_link: 'http://g.co/news' // string, shortened link in tweet text photos: image: 'http://service.com/some/cool/image/12345.jpg' // The raw url to the largest image in tweet source: service: 'twitter' name: 'Twitter' description: 'Social networking and microblogging service utilising instant messaging, SMS or a web interface.' domain: 'twitter.com' external_uri: 'https://twitter.com/'
Deployment
In order to run, hummingbird requires:
To deploy (assuming node.js is installed):
git clone git@github.com:chapmanu/hummingbird.git
- Edit
config.js
and set the necessary API credentials and server information. You can edit environment-specific credentials in the various environment files. Settings in environment config files will override config.js when that environment is specified on run. - Run
node app.js
and then go get yourself a beer!