clucker provides access to most of Twitter's public API access endpoints, including both REST and streaming endpoints.
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.).
For Chicken 5+ clucker can be used with (import clucker). For Chicken 4 clucker can be used with (use clucker).
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.
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.
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.
- 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.
- 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.
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
- direct-messages-show #!key idprocedure
- search-tweets #!key q geocode lang locale result_type count until since_id max_id include_entities callbackprocedure
- mutes-users-ids #!key cursorprocedure
- lists-statuses #!key list_id slug owner_screen_name owner_id since_id max_id count include_entities include_rtsprocedure
- 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
- saved-searches-show-:id #!key idprocedure
- geo-id-:place-id #!key place_idprocedure
- geo-search #!key lat long query ip granularity accuracy max_results contained_within attribute:street_addressprocedure
- trends-place #!key id excludeprocedure
- trends-closest #!key lat longprocedure
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))))
- Support for Chicken 5
- Bugfix in streaming tweet counts
- Initial release.
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.