chickadee » clucker

clucker

clucker provides access to most of Twitter's public API access endpoints, including both REST and streaming endpoints.

Description

This extension provides access to most of Twitter's RESTful and streaming API endpoints. Notable exceptions include most POST endpoints used, for example, for creating tweets through the API. This means that in its current form, clucker is not suitable for projects that require posting tasks (e.g., building a Twitter client, bot, etc.).

Source Code

https://github.com/n3mo/clucker

Requirements

Usage

For Chicken 5+ clucker can be used with (import clucker). For Chicken 4 clucker can be used with (use clucker).

API

Parameters

Note that the following two parameters work together to control streaming API endpoints. That is, connections to streaming API endpoints are kept open until max-tweets or global-max-seconds are reached (whichever occurs first). At least one of these two parameters should be set to a reasonable value to allow streaming endpoints connections to close gracefully.

max-tweetsparameter

Determines the maximum number of tweets to be returned by Twitter's streaming endpoints. Streaming endpoints are kept open (barring any network issues) until roughly max-tweets are returned. This is called "max-tweets" because Twitter offers no guarantees about the number of tweets you will receive (and clucker does not count incoming tweets---it simply pipes results to the current port). For example, deleted tweets still count toward your request even though the JSON response for the tweet will be essentially empty. Thus if max-tweets is set to 100, you should expect up to 100 tweets (and likely exactly 100), but should anticipate getting <100. The default is set to 999999999999999999 to be large enough to effectively leave the endpoint open indefinitely.

global-max-secondsparameter

Determines the timeout for streaming endpoints. Any call to a streaming endpoint will remain open for global-max-seconds (or until max-tweets have been returned, whichever occurs first). The default is set to 999999999999999999 to be large enough to effectively leave the endpoint open indefinitely.

Authentication Procedures

twitter-service #!key access-token access-token-secretprocedure

Calls to Twitter's APIs must be signed with oauth. This procedure accepts the access-token and access-token-secret provided by Twitter (when you create a developer account) and returns a structure for use as a "service" when calling with-oauth.

twitter-token-credential #!key access-token access-token-secretprocedure

Calls to Twitter's APIs must be signed with oauth. This procedure accepts the access-token and access-token-secret provided by Twitter (when you create a developer account) and returns a structure for use as a "token-credential" when calling with-oauth.

Streaming API Endpoint Procedures

statuses-filter #!key delimited stall_warnings follow track locations languageprocedure

Searchable streaming API---tweets are returned in real time according to the provided keyword filters. This method runs forever, unless the global parameters max-tweets or global-max-seconds are set to something to less than the defaults. Tweets are returned as line-oriented JSON to the current-output-port (one tweet = one line = one JSON object). Keyword parameters are described on Twitter's developer documentation.

statuses-sample #!key delimited stall_warningsprocedure

Random access streaming endpoint. This returns a random sample of all tweets occuring in real time (up to 1% of Twitter's total volume). This method runs forever, unless the global parameters max-tweets or global-max-seconds are set to something. Tweets are returned as line-oriented JSON to the current-output-port. Keyword parameters are described on Twitter's developer documentation.

REST API Endpoint Procedures

For the following procedures, tweets are returned to the current-output-port as JSON strings in the format provided by Twitter's API. In other words, results are simply passed as-is to the current-output-port (and can be parsed with a tool such as medea). Which keyword parameters are optional versus required, as well as what values can be passed are subject to frequent revision by Twitter. As such, users should consult Twitter's developer documentation for details about how to use each procedure's keywords.

statuses-mentions-timeline #!key count since_id max_id trim_user contributor_details include_entitiesprocedure
statuses-user-timeline #!key user_id screen_name since_id count max_id trim_user exclude_replies contributor_details include_rtsprocedure
statuses-home-timeline #!key count since_id max_id trim_user exclude_replies contributor_details include_entitiesprocedure
statuses-retweets-of-me #!key count since_id max_id trim_user include_entities include_user_entitiesprocedure
statuses-retweets-:id #!key id count trim_userprocedure
statuses-show-:id #!key id trim_user include_my_retweet include_entitiesprocedure
statuses-retweeters-ids #!key id cursor stringify_idsprocedure
statuses-lookup #!key id include_entities trim_user map tweet_modeprocedure
direct-messages-sent #!key since_id max_id count page include_entitiesprocedure
direct-messages-show #!key idprocedure
search-tweets #!key q geocode lang locale result_type count until since_id max_id include_entities callbackprocedure
direct-messages #!key since_id max_id count include_entities skip_statusprocedure
friendships-no-retweets-ids #!key stringify_idsprocedure
friends-ids #!key user_id screen_name cursor stringify_ids countprocedure
followers-ids #!key user_id screen_name cursor stringify_ids countprocedure
friendships-incoming #!key cursor stringify_idsprocedure
friendships-outgoing #!key cursor stringify_idsprocedure
friendships-show #!key source_id source_screen_name target_id target_screen_nameprocedure
friends-list #!key user_id screen_name cursor count skip_status include_user_entitiesprocedure
followers-list #!key user_id screen_name cursor count skip_status include_user_entitiesprocedure
friendships-lookup #!key screen_name user_idprocedure
account-settingsprocedure
account-verify-credentials #!key include_entities skip_status include_emailprocedure
blocks-list #!key include_entities skip_status cursorprocedure
blocks-ids #!key stringify_ids cursorprocedure
users-lookup #!key screen_name user_id include_entitiesprocedure
users-show #!key user_id screen_name include_entitiesprocedure
users-profile-banner #!key user_id screen_nameprocedure
mutes-users-ids #!key cursorprocedure
mutes-users-list #!key cursor include_entities skip_statusprocedure
users-suggestions-:slug #!key slug langprocedure
users-suggestions-:slug-members #!key slugprocedure
favorites-list #!key user_id screen_name count since_id max_id include_entitiesprocedure
lists-list #!key user_id screen_name reverseprocedure
lists-statuses #!key list_id slug owner_screen_name owner_id since_id max_id count include_entities include_rtsprocedure
lists-memberships #!key user_id screen_name count cursorprocedure
lists-subscribers #!key list_id slug owner_screen_name owner_id count cursor include_entities skip_statusprocedure
lists-subscribers-show #!key owner_screen_name owner_id list_id slug user_id screen_name include_entities skip_statusprocedure
lists-members-show #!key list_id slug user_id screen_name owner_screen_name owner_id include_entities skip_statusprocedure
lists-members #!key list_id slug owner_screen_name owner_id count cursor include_entities skip_statusprocedure
lists-show #!key list_id slug owner_screen_name owner_idprocedure
lists-subscriptions #!key user_id screen_name count cursorprocedure
lists-ownerships #!key user_id screen_name count cursorprocedure
saved-searches-listprocedure
saved-searches-show-:id #!key idprocedure
geo-id-:place-id #!key place_idprocedure
geo-reverse-geocode #!key lat long accuracy granularity max_results callbackprocedure
trends-place #!key id excludeprocedure
trends-availableprocedure
application-rate-limit-status #!key resourcesprocedure
help-configurationprocedure
help-languagesprocedure
help-privacyprocedure
help-tosprocedure
trends-closest #!key lat longprocedure

Examples

Note that careful use of this egg requires that you follow Twitter's API rate limits. These rate limits must be managed by the calling code (e.g., by consulting the application-rate-limit-status procedure to determine the number of remaining calls to the API endpoint(s), and then restricting the access rate accordingly). See Twitter's developer documentation for up-to-date details on rate limits for each endpoint.

The following minimal example queries the friends-list REST API endpoint, returning the first 10 friends of the @NASA Twitter account. Note that you will need to first request a Twitter developer account, set up a Twitter application, and generate the appropriate consumer-key, consumer-secret, access-token, and access-token-secret (this is all done on Twitter's developer website). Those secret values must replace the dummy-coded secrets in the example code before running.

(import clucker oauth-client)
;;; Set up oauth credentials. You will need to insert your own
;;; consumer-key, consumer-secret, access-token, and
;;; access-token-secret (these can be found in your Twitter developer
;;; account after creating a Twitter application)
(let* ((twitter-app
	(twitter-service
	 #:consumer-key "yourconsumerkeyhere"
	 #:consumer-secret "yourconsumersecrethere"))
       (user-tokens
	(twitter-token-credential
	 #:access-token "youraccesstokenhere"
	 #:access-token-secret "youraccesstokensecrethere")))
  ;; This intercepts all calls to Twitter and signs them with
  ;; the user's oauth credentials
  (with-oauth
   twitter-app user-tokens
   (lambda ()
     ;; Call the actual endpoint you want here
     (friends-list #:screen_name "NASA"
		   #:count 10))))

About This Egg

Author

Nick Van Horn

Version History

0.11
Support for Chicken 5
0.10
Bugfix in streaming tweet counts
0.9
Initial release.

License

Copyright (c) 2015-2020, Nicholas M. Van Horn
All rights reserved.
 
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. The name of the authors may not be used to endorse or promote products
   derived from this software without specific prior written permission.
 
THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Contents »