This is the HearPlanet supported Python driver for HearPlanet’s public API.
This API supports queries to HearPlanet’s database of Points of Interest, Articles, Images and Audio files.
If you need additional support, please visit
The easiest way to get started with the driver is to install it from the Python Package Index.
pip install HearPlanetAPI
First you need to obtain API access credentials from HearPlanet.
Create a configuration file containing your credentials, by copying and customizing hearplanet.cfg.example to one, or both, of the following:
To use the driver in a Python program, just …
from hearplanet import HearPlanet api = HearPlanet()
example.py is provided with the driver as a reference.
The driver allows you to access the HearPlanet API, sending requests and getting data back.
One thing to be aware of is the behavior of the query modifier functions. These return new query instances, so base queries can be set up and then modified in different ways to produce new queries.
You specify the table (type of object) you want to search for, the search terms, and various filters and modifiers. The search is executed when you access the response object.
Many of the HearPlanet database tables can be accessed. However, generally if you are only making requests, you will only need to be accessing the “article” and/or “poi” tables. The general layout looks something like this:
table('poi') table('article') fetch({id}, objects={'object'}, size={'image_size_code'}) search() term('A Query Term') point({'lat':'37.0', 'lng':'-122.5'}) location('123 Address St., Anytown') filters({'key':'value'}) featured()
First you would select the table (poi or article). If you already know the unique identifier of the poi or article, you can use fetch(). If you would like to get the “featured” articles, then just use featured(). Otherwise, use search() plus one or more of term(), point() and location(). Finally, you can add filters to further refine your search.
Other tables of interest might be “langugages” and “categories.” For a complete list, consult the API documentation.
Searches for POI’s and Articles can be performed based on location or query term.
Location searches return POI’s and Articles near a point – either a latitude/longitude or an address (or other geocodable location). If you give both point() and location(), objects near location will be used, and distances to that location will be calculated from point. Examples:
point({'lat':'37.0', 'lng':'-122.5'}) location('123 Address St., Anytown')
Query Term searches do a full-text search in the title of the POI or Article.
term('Pizza')
In combination:
# Search for POI's with "Pizza" in their title located in # Chicago, calculating distances from the given point. req = api.table('poi').search() req = req.term('Pizza').location('Chicago, IL') req = req.point({'lat':'37.0', 'lng':'-122.5'})
Fetch a particular POI or Article if you have its id:
req = api.table('article').fetch(999999)
If you only want some of the objects associated with an article, you can request them specifically. For example, if an article has email addresses associated with it:
req = api.table('article').fetch(999999, 'emails')
Images take an optional ‘size’ parameter, for example ‘T’ for thumbnail:
req = api.table('article').fetch(999999, 'images', 'T')
The full list of article objects is:
Get featured Articles :
req = api.table('article').featured()
Filters can be applied to the searches:
req = req.filters({'ch':'hearplanet'}) req = req.filters({'lang':'fr'}) req = req.filters({'bbox':'(37.3,-122.8)(37.6,-120.0)'}) req = req.filters({'radius':15'}) # search radius in kilometers
Request modifiers are used for paging results, selecting the text format and the amount of data returned.
You can either use limit() and offset() together, or just use page(). The default values for offset and limit are 0 and 10, respectively. If you use page(), just specify an integer page number from 1 to N. The default page length is 10.
limit(max_rows) offset(offset) page(page_num, limit=DEFAULT_LIMIT) format(format) # ('HTML', 'HTML-RAW', 'XHTML', 'PLAIN', 'AS-IS') depth(depth) # ('min', 'poi', 'article', 'section', 'section_text', 'all',)
poi_list = api.table('poi').search().term('Pizza').depth('poi').page(1).objects()
first_poi = poi_list[0] first_article_id = first_poi.articles[0].id print first_poi
api = HearPlanet()
req = api.table('poi').search()
req = req.term('Golden Gate') req = req.location('San Francisco, CA')
req = req.filters({'ch':'wikipedia'})
req = req.page(1)
objects = req.objects()
for poi in objects: print poi.title
pois = api.table('poi').search().term('Golden Gate').location('San Francisco, CA').filters({'ch':'wikipedia'}).page(1).objects()
Unit Tests are provided to ensure the driver is functioning as expected. The unit tests also serve as examples of various API requests.
python test_hearplanet.py
The Python driver handles URL encoding, therefore all parameters passed to the driver should be in their un-encoded.