API Reference¶
OGRe Query Handler
OGRe
– retriever object template
OGRe.fetch()
– method for making a retriever fetch data
OGRe.get()
– alias of OGRe.fetch()
-
class
ogre.api.
OGRe
(keys)¶ Create objects that contain API keys and API access points.
OGRe was made a class to avoid requiring API keys with every API call. Since this is a library meant for developers, it didn’t seem appropriate to use a configuration file. Also, importing the keys from the OS environment subjects them to data leak. This way developers are responsible for keeping their keys safe, and they can use the environment if they choose. Twython, the Twitter API wrapper, also uses this scheme.
fetch()
– method for retrieving data from a public sourceget()
– backwards-compatible alias offetch()
-
fetch
(sources, media=('image', 'sound', 'text', 'video'), keyword='', quantity=15, location=None, interval=None, **kwargs)¶ Get geotagged data from public APIs.
See also
ogre.validation.validate()
describes the format each parameter must have. It is also a good idea to check the module of any sources that will be searched (e.g.ogre.Twitter.twitter()
) for extra constraints on parameters.Parameters: - sources (tuple) – Specify public APIs to get content from (required). “Twitter” is currently the only supported source.
- media (tuple) – Specify content mediums to fetch. “image”, “sound”, “text”, and “video” are supported.
- keyword (str) – Specify search criteria.
- quantity (int) – Specify a quota of results to fetch.
- location (tuple) – Specify a place (latitude, longitude, radius, unit) to search.
- interval (tuple) – Specify a period of time (earliest, latest) to search.
Raises: ValueError
Return type: dict
Returns: GeoJSON FeatureCollection
Note
Additional runtime modifiers may be specified to change the way results are retrieved. Runtime modifiers are relayed to each source module, and that is where they are documented.
-
get
(sources, keyword='', what=('image', 'sound', 'text', 'video'), when=None, where=None, how_many=15, **kwargs)¶ Provide a backwards-compatible alias of
fetch()
.Parameters: - sources (tuple) – This parameter corresponds directly in
fetch()
. - keyword (str) – This parameter corresponds directly in
fetch()
. - what (tuple) – This parameter corresponds to media in
fetch()
. - when (tuple) – This parameter corresponds to interval in
fetch()
. - where (tuple) – This parameter corresponds to location in
fetch()
. - how_many (int) – This parameter corresponds to quantity in
fetch()
.
Return type: dict
Returns: GeoJSON FeatureCollection
- sources (tuple) – This parameter corresponds directly in
-
OGRe Twitter Interface
twitter()
: method for fetching data from Twitter
-
ogre.Twitter.
sanitize_twitter
(keys, media=('image', 'text'), keyword='', quantity=15, location=None, interval=None)¶ Validate and prepare parameters for use in Twitter data retrieval.
See also
ogre.validation.validate()
describes the format each parameter must have.Parameters: - keys (dict) – Specify Twitter API keys. Twitter requires a “consumer_key” and “access_token”.
- media (tuple) – Specify content mediums to make lowercase and deduplicate. “image” and “text” are supported mediums.
- keyword (str) – Specify search criteria to incorporate the requested media in.
- quantity (int) – Specify a quota of results.
- location (tuple) – Specify a location to format as a Twitter geocode (“<latitude>,<longitude>,<radius><unit>”).
- interval (tuple) – Specify earliest and latest moments to convert to Twitter Snowflake IDs.
Raises: ValueError
Return type: tuple
Returns: Each passed parameter is returned (in order) in the proper format.
-
ogre.Twitter.
twitter
(keys, media=('image', 'text'), keyword='', quantity=15, location=None, interval=None, **kwargs)¶ Fetch Tweets from the Twitter API.
See also
sanitize_twitter()
describes more about the format each parameter must have.Parameters: - keys (dict) – Specify an API key and access token.
- media (tuple) – Specify content mediums to fetch. “text” or “image” are supported mediums.
- keyword (str) – Specify search criteria. “Queries can be limited due to complexity.” If this happens, no results will be returned. To avoid this, follow Twitter Best Practices including the following: “Limit your searches to 10 keywords and operators.”
- quantity (int) – Specify a quota of results to fetch. Twitter will return 15 results by default, and up to 100 can be requested in a single query. If a number larger than 100 is specified, the retriever will make multiple queries in an attempt to satisfy the requested quantity, but this is done on a best effort basis. Whether the specified number is returned or not depends on Twitter.
- location (tuple) – Specify a place (latitude, longitude, radius, unit) to search. Since OGRe only returns geotagged results, the larger the specified radius, the fewer results will be returned. This is because of the way Twitter satisfies geocoded queries. It uses so-called “fuzzy matching logic” to deduce the location of Tweets posted publicly without location data. OGRe filters these out.
- interval (tuple) – Specify a period of time (earliest, latest) to search. “The Search API is not complete index of all Tweets, but instead an index of recent Tweets.” Twitter’s definition of “recent” is rather vague, but when an interval is not specified, “that index includes between 6-9 days of Tweets.”
- strict_media (bool) – Specify whether to only return the requested media (defaults to False). Setting this to False helps build caches faster at no additional cost. For instance, since Twitter automatically sends the text of a Tweet back, if (“image”,) is passed for media, the text on hand will only be filtered if strict_media is True.
- secure (bool) – Specify whether to prefer HTTPS or not (defaults to True).
- test (bool) – Specify whether a the current request is a trial run. This affects what gets logged and should be accompanied by the next 3 parameters (test_message, api, and network).
- test_message (str) – Specify a description of the test to log. This is ignored if the test parameter is False.
- api (callable) – Specify API access point (for dependency injection).
- network (callable) – Specify a network access point (for dependency injection).
Raises: OGReError, OGReLimitError, TwythonError
Return type: list
Returns: GeoJSON Feature(s)
See also
Visit https://dev.twitter.com/docs/using-search for tips on how to build queries for Twitter using the keyword parameter. More information may also be found at https://dev.twitter.com/docs/api/1.1/get/search/tweets.
OGRe Parameter Validator
validate()
– check OGRe parameters for errors
sanitize()
– validate and cleanse OGRe parameters
-
ogre.validation.
sanitize
(media=('image', 'sound', 'text', 'video'), keyword='', quantity=15, location=None, interval=None)¶ Validate and transform input to expected types.
See also
validate()
describes the format each parameter must have.Parameters: - media (tuple) – Specify content mediums to make lowercase and deduplicate.
- keyword (str) – Specify search criteria.
- quantity (int) – Specify a quota of results.
- location (tuple) – Specify a location to make numeric (latitude, longitude, radius) and lowercase (unit).
- interval (tuple) – Specify earliest and latest moments to make numeric and sort in ascending order.
Return type: tuple
Returns: sanitized parameters (media, keyword, quantity, location, interval)
-
ogre.validation.
validate
(media=('image', 'sound', 'text', 'video'), keyword='', quantity=15, location=None, interval=None)¶ Check common interface parameters for errors and validity.
Parameters: - media (tuple) – “image”, “sound”, “text”, and “video” are valid mediums.
- keyword (str) – Valid criteria varies by source.
- quantity (int) – Specify a positive quota of desired results.
- location (tuple) – Specify a location (latitude, longitude, radius, unit) composed of 3 numbers and a string, respectively. “km” and “mi” are supported units.
- interval (tuple) – Specify a period of time (earliest, latest) composed of 2 POSIX timestamps (positive numbers). The order of earliest/latest moments does not matter as the lower number will be considered earliest.
Raises: ValueError