Tutorial¶
Follow this simple guide to quickly get started using OGRe.
Installation¶
To get OGRe, use one of the following methods:
- pip (recommended)
$ pip install ogre
$ easy_install ogre
$ git clone http://github.com/dmtucker/ogre.git
$ cd ogre
$ python setup.py install
Note
This method requires separate installation(s) for dependencies!
Usage¶
To use OGRe, you must import it into your module:
from ogre import OGRe
Next, create an OGRe instance with your API credentials:
retriever = OGRe(
keys={
'Twitter': {
'consumer_key': 'xxxxxxxxxxxxxxxxxxxxxx',
'access_token': 'xxxxxxxxxxxxxxxxxxxxxxxxxxxx' +
'xxxxxxxxxxxxxxxxxxxxxxxxxxxx' +
'xxxxxxxxxxxxxxxxxxxxxxxxxxxx' +
'xxxxxxxxxxxxxxxxxxxxxxxxxxxx'
}
}
)
Finally, make queries using the .get method.
Note
“The [Twitter] Search API is not complete index of all Tweets, but instead an index of recent Tweets. At the moment that index includes between 6-9 days of Tweets.”
OGRe may be also be executed directly as shown below.
$ python -m ogre
or (if OGRe was installed with pip)
$ ogre
As one would expect, API keys are necessary whenever OGRe is run, and they may be passed one of two ways: the keys parameter or via environment variables. If the latter is preferred, the following table shows what variables are needed for each source:
Source | Key Variable(s) |
---|---|
TWITTER_CONSUMER_KEY, TWITTER_ACCESS_TOKEN |
Examples¶
To find 50 image-less Tweets posted within 1km of Twitter headquarters, use:
retriever.fetch(
sources=('Twitter',),
media=('text',),
keyword='',
quantity=50,
location=(37.781157, -122.398720, 1, 'km'),
interval=None
)
Note
Either a keyword or location is required.
To issue the same query directly from the command line, use the following:
$ python -m ogre --keys "{\
> 'Twitter': {\
> 'consumer_key': '<Insert Twitter Consumer Key.>',\
> 'access_token': '<Insert Twitter Access Token.>'\
> }\
> }\
> --sources Twitter \
> --media text \
> --quantity 50 \
> --location 37.781157 -122.398720 1 km
Alternatively, environment variables are checked when keys are unspecified.
$ export TWITTER_CONSUMER_KEY='<Insert Twitter Consumer Key.>'
$ export TWITTER_ACCESS_TOKEN='<Insert Twitter Access Token.>'
$ python -m ogre --sources Twitter --media text \
> --quantity 50 --location 37.781157 -122.398720 1 km
See also
For a description of all available command line arguments, run:
$ python -m ogre --help
Results return as a single GeoJSON FeatureCollection. So, the example above could return:
{
"type": "FeatureCollection",
"features": [
{
"geometry": {
"type": "Point",
"coordinates": [
-122.3970807,
37.77541704
]
},
"type": "Feature",
"properties": {
"source": "Twitter",
"text": "Sending good thoughts to my babe @annecurtissmith...",
"timestamp": "2014-04-04T02:03:28.431000Z"
}
},
{
"geometry": {
"type": "Point",
"coordinates": [
-122.41160509,
37.78093192
]
},
"type": "Feature",
"properties": {
"source": "Twitter",
"text": "I'm at Huckleberry Bicycles...",
"timestamp": "2014-04-04T02:03:13.190000Z"
}
},
...
]
}
Say we wanted to run the same query and possibly have images returned too. Additional mediums can be specified with subsequent media flags like this:
$ python -m ogre \
> --sources Twitter \
> --media text --media image \
> --quantity 50 \
> --location 37.781157 -122.398720 1 km