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 source

get() – backwards-compatible alias of fetch()

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

Note

get() is deprecated. fetch() should be used instead.

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