chbrown / twttr

Twitter API client for Clojure supporting REST and Streaming endpoints

twttr

Twitter API client for Clojure, using aleph and clj-oauth, supporting REST and Streaming endpoints.

twttr is a much simplified fork of twitter-api, mostly due to using aleph instead of http.async.client. In particular, streaming is now much easier. Also removed: all ^:dynamic vars, and all but one macro.

Install

twttr is on Clojars:

[twttr "3.2.3"]

Getting started

Assuming you've got your OAuth credentials in hand (procuring them is outside the scope of this library), the easiest way to use them in your Clojure project is via environment variables:

export CONSUMER_KEY=l4VAFAKEFAKEFAKEpy7R7
export CONSUMER_SECRET=dVnTimJtFAKEFAKEFAKEFAKEFAKEFAKEBVYnO91BR1G
export ACCESS_TOKEN=195648015-OIHb87zuFAKEFAKEFAKEFAKEFAKEFAKEb5aLUMYo
export ACCESS_TOKEN_SECRET=jsVg1HFAKEFAKEFAKEFAKEFAKEFAKE4yfOLC5cXA9fcXr

And then (in the same shell session!) run lein repl or whatever you're using to kick off your Clojure code:

; save this to `dev/user.clj` in your project
(ns user
  (:require [twttr.api :as api]
            [twttr.auth :refer [env->UserCredentials]]))

; read credentials from environment variables, namely:
; CONSUMER_KEY, CONSUMER_SECRET, ACCESS_TOKEN, and ACCESS_TOKEN_SECRET
(def creds (env->UserCredentials))

; the "https://api.twitter.com/1.1/users/show.json" Resource URL
; becomes the "users-show" function
(api/users-show creds :params {:screen_name "jack"})
;=> {:id 12, :verified true, :created_at "Tue Mar 21 20:50:14 +0000 2006", ...}

; the value returned is the body of the response,
; with the rest of the response attached as metadata:
(meta *1)
;=> {:request-time 263,
;    :headers {"x-rate-limit-reset" "1495550008", "last-modified" "Tue, 23 May 2017 14:29:28 GMT",
;              "x-rate-limit-limit" "900", "x-rate-limit-remaining" "898", ...},
;    :status 200,
;    :connection-time 269}

; update your status
(api/statuses-update creds :params {:status "Well that was quick."})

; get a taste of the sample stream
(def stream (api/statuses-sample creds))
(def first10 (doall (take 10 stream)))
(-> stream meta :body (.close))
(map :text first10)

Testing

The tests require that credentials be provided via environment variables as described above.

Then run lein test, which can take a minute since many of the tests involve calling the Twitter API and waiting for an appropriate response. If all tests completed successfully, the test output will end with a message like:

Ran 27 tests containing 68 assertions.
0 failures, 0 errors.

License

Distributed under the Eclipse Public License, same as Clojure.

• Copyright (C) 2017–2019 Christopher Brown
• Copyright (C) 2011 StreamScience