From 44a022fe7a74788e755ab9c41754fcb2d2726814 Mon Sep 17 00:00:00 2001 From: Jonas Geduldig Date: Sun, 3 Feb 2013 10:18:31 -0500 Subject: [PATCH] Update readme Update readme --- MANIFEST | 2 -- README.md | 44 ++++++++++++++++++++------------------------ 2 files changed, 20 insertions(+), 26 deletions(-) diff --git a/MANIFEST b/MANIFEST index 55d347b..b2ef64e 100644 --- a/MANIFEST +++ b/MANIFEST @@ -1,6 +1,4 @@ # file GENERATED by distutils, do NOT edit -CHANGES.txt -README.txt setup.py twittergeo/Geocoder.py twittergeo/SearchGeo.py diff --git a/README.md b/README.md index 71deaeb..7984894 100644 --- a/README.md +++ b/README.md @@ -1,66 +1,62 @@ -### UNDER DEVELOPMENT ### - -_Expected release date is sometime in early February 2013_ - ---- - -### TwitterGeo ### +# TwitterGeo # _Scripts for geocoding tweets and for downloading images embedded in tweets._ +### Getting Location and Embedded Images... ### + TwitterGeo contains command line scripts for geocoding tweets and extracting embedded images from tweets from twitter.com. The scripts take one or more search words as command line arguments. The scripts download old tweets using Twitter's REST API and download new tweets using Twitter's Streaming API. About 1% or 2% of tweets contain latitude and longitude. Of those tweets that do not contain coordinate data, about 60% have the user's profile location, a descriptive text field that may or not be accurate. Using Google's Maps API, we can geocode these tweets, which locates about half of all tweets, a portion of which are suspect. -Use the location option to restrict searches to a geographic location. Twitter returns tweets that either contain geocode in the location region or tweets from users whose profile location is in the specified region. +Use the location option to restrict searches to a geographic location. Twitter returns tweets that either contain coordinates in the location region or tweets from users whose profile location is in the specified region. Google does not require autentication, but it does enforce a daily limit of about 2,500 requests per day and about 10 requests per second. -The Twitter API's require OAuth credentials which you can get by creating an application on dev.twitter.com. Once you have your OAuth secrets and keys, copy them into twittergeo/credentials.txt. Alternatively, specify the credentials file on the command line. +The Twitter API requires OAuth credentials which you can get by creating an application on dev.twitter.com. Once you have your OAuth secrets and keys, copy them into twittergeo/credentials.txt. Alternatively, specify the credentials file on the command line. Twitter restricts searching old tweets to within roughly the past week. Twitter also places a bandwidth limit on searching current tweet, but you will notice this only when you are searching a popular word. When this limit occurs the total number of skipped tweets is printed and the connection is maintained. -# Features # +### Features ### *The following modules run as command line scripts and write tweets to the console.* -### SearchGeo ### +***SearchGeo*** Prints old tweets and their location information and coordinates when possible. -### StreamGeo ### +***StreamGeo*** Prints new tweets and their location information and coordinates when possible. -### SearchPics ### +***SearchPics*** Prints old tweets, their coordinates and URLs of any embedded photos. To download the photos use the -photo_dir option. To get tweets only from a specific geographic region use the -location. -### StreamPics ### +***StreamPics*** Prints new tweets, their coordinates and URLs of any embedded photos. To download the photos use the -photo_dir option. To get tweets only from a specific geographic region use the -location. -*These are utility modules.* +*This is utility module.* -### Geocoder ### +***Geocoder*** -A wrapper for pygeocoder that provides a few Twitter helper methods. It adds throttling to respect Google's daily quota and rate limit. It also provides a caching mechanism for storing geocode lookups to a text file. The caching is only partially effective because user can enter their location in any format. +A wrapper for the pygeocoder package. It adds throttling to respect Google's daily quota and rate limit. It also provides a caching mechanism for storing geocode lookups to a text file. The caching is only partially effective because user can enter their location in any format. There are also some Twitter specific methods. -# Installation # +### Installation ### 1. On a command line, type: -`pip install twittergeo` + pip install twittergeo 2. Either copy your OAuth consumer secret and key and your access token secret and key into twittergeo/credentials.txt, or copy them into another file which you will specify on the command line. See credentials.txt for the expected file format. -3. Then, run a script type with '-m' option, for example: +3. Run a script type with '-m' option, for example: -`python -m twittergeo.StreamGeo zzz` -`python -m twittergeo.StreamGeo zzz -oauth ./my_credentials.txt` + python -m twittergeo.StreamGeo zzz + python -m twittergeo.StreamGeo zzz -oauth ./my_credentials.txt -# External Dependencies # +### External Dependencies ### This package uses the following external packages. @@ -68,6 +64,6 @@ This package uses the following external packages. * pygeocoder - for geo-referencing using Google's Maps service * fridge - for caching latitudes and longitudes in a persistant dict -# Contributors # +### Contributors ### Jonas Geduldig \ No newline at end of file