{
    "info": {
        "author": "Liam Kirsher",
        "author_email": "liam@hearplanet.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 3 - Alpha",
            "Environment :: Console",
            "Intended Audience :: Developers",
            "License :: OSI Approved :: Apache Software License",
            "Natural Language :: English",
            "Programming Language :: Python",
            "Topic :: Software Development :: Libraries :: Python Modules"
        ],
        "description": "About\n=====\n\nThis is the HearPlanet supported Python driver for HearPlanet\u2019s public\nAPI.\n\nThis API supports queries to HearPlanet\u2019s database of Points of\nInterest, Articles, Images and Audio files.\n\nIf you need additional support, please visit http://www.hearplanet.com/\n\nOverview\n========\n\nSetup\n-----\n\nThe easiest way to get started with the driver is to install it from the\nPython Package Index.\n\n::\n\n    pip install HearPlanetAPI\n\nFirst you need to obtain API access credentials from HearPlanet.\n\nCreate a configuration file containing your credentials, by copying and\ncustomizing hearplanet.cfg.example to one, or both, of the following:\n\n1. /etc/hearplanet.cfg ### Site-wide\n2. ~/.hearplanet.cfg ### Individual\n\nTo use the driver in a Python program, just \u2026\n\n::\n\n    from hearplanet import HearPlanet  \n    api = HearPlanet()\n\nexample.py is provided with the driver as a reference.\n\nDependencies\n------------\n\nMinimum Python version 2.5.\n\n`Requests`_\n\nBasic Design\n------------\n\nThe driver allows you to access the HearPlanet API, sending requests and\ngetting data back.\n\nOne thing to be aware of is the behavior of the query modifier\nfunctions. These return new query instances, so base queries can be set\nup and then modified in different ways to produce new queries.\n\nYou specify the table (type of object) you want to search for, the\nsearch terms, and various filters and modifiers. The search is executed\nwhen you access the response object.\n\nTables\n------\n\nMany of the HearPlanet database tables can be accessed. However,\ngenerally if you are only making requests, you will only need to be\naccessing the \u201carticle\u201d and/or \u201cpoi\u201d tables. The general layout looks\nsomething like this:\n\n::\n\n    table('poi')\n    table('article')\n        fetch({id}, objects={'object'}, size={'image_size_code'})\n        search()\n            term('A Query Term')\n            point({'lat':'37.0', 'lng':'-122.5'})\n            location('123 Address St., Anytown')\n            filters({'key':'value'})\n        featured()\n\nFirst you would select the table (poi or article). If you already know\nthe unique identifier of the poi or article, you can use fetch(). If you\nwould like to get the \u201cfeatured\u201d articles, then just use featured().\nOtherwise, use search() plus one or more of term(), point() and\nlocation(). Finally, you can add filters to further refine your search.\n\nOther tables of interest might be \u201clangugages\u201d and \u201ccategories.\u201d For a\ncomplete list, consult the `API documentation`_.\n\nSearch Requests\n---------------\n\nSearches for POI\u2019s and Articles can be performed based on location or\nquery term.\n\nLocation searches return POI\u2019s and Articles near a point \u2013 either a\nlatitude/longitude or an address (or other geocodable location). If you\ngive both point() and location(), objects near location will be used,\nand distances to that location will be calculated from point. Examples:\n\n::\n\n    point({'lat':'37.0', 'lng':'-122.5'})\n    location('123 Address St., Anytown')\n\nQuery Term searches do a full-text search in the title of the POI or\nArticle.\n\n::\n\n    term('Pizza')\n\nIn combination:\n\n::\n\n    # Search for POI's with \"Pizza\" in their title located in\n    # Chicago, calculating distances from the given point.\n    req = api.table('poi').search()\n    req = req.term('Pizza').location('Chicago, IL')\n    req = req.point({'lat':'37.0', 'lng':'-122.5'})\n\nFetch a particular POI or Article if you have its id:\n\n::\n\n    req = api.table('article').fetch(999999)\n\nIf you only want some of the objects associated with an article, you can\nrequest them specifically. For example, if an article has email\naddresses associated with it:\n\n::\n\n    req = api.table('article').fetch(999999, 'emails')\n\nImages take an optional \u2018size\u2019 parameter, for example \u2018T\u2019 for thumbnail:\n\n::\n\n    req = api.table('article').fetch(999999, 'images', 'T')\n\nThe full list of article objects is:\n\n-  addresses\n-  audio\n-  categories\n-  details\n-  emails\n-  images\n-  phones\n-  rating\\_average\n-  ratings\n-  reviews\n-  sections\n-  sections\\_f\n-  tags\n-  websites\n\nGet featured Articles :\n\n::\n\n    req = api.table('article').featured()\n\nSearch Request Filters\n----------------------\n\nFilters can be applied to the searches:\n\n::\n\n    req = req.filters({'ch':'hearplanet'})\n    req = req.filters({'lang':'fr'})\n    req = req.filters({'bbox':'(37.3,-122.8)(37.6,-120.0)'})\n    req = req.filters({'radius':15'}) # search radius in kilometers\n\nRequest modifiers\n-----------------\n\nRequest modifiers are used for paging results, selecting the text format\nand the amount of data returned.\n\nYou can either use limit() and offset() together, or just use page().\nThe default values for offset and limit are 0 and 10, respectively. If\nyou use page(), just specify an integer page number from 1 to N. The\ndefault page length is 10.\n\n::\n\n    limit(max_rows)\n    offset(offset)\n    page(page_num, limit=DEFAULT_LIMIT)\n    format(format) # ('HTML', 'HTML-RAW', 'XHTML', 'PLAIN', 'AS-IS')\n    depth(depth) # ('min', 'poi', 'article', 'section',\n                    'section_text', 'all',)\n\n-  The format modifiers change the formatting of the section text.\n   Normally this is set on the backend and you don\u2019t have to worry about\n   it. However, if necessary you can override it.\n\n-  The depth modifiers change the amount of information that is\n   returned. That\u2019s primarily for performance enhancement, when\n   accessing the API over a slow network. For example, make a shallow\n   initial search using the poi.json endpoint at depth \u2018poi\u2019 to get a\n   list of POI\u2019s and their Articles. Then the full Article can be\n   selected by the user, and a second request made for just that Article\n   using fetch().\n\nFirst do a shallow search of POI\u2019s that have \u201cPizza\u201d in their title\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n::\n\n    poi_list = api.table('poi').search().term('Pizza').depth('poi').page(1).objects()\n\nGet the id of the first Article in the first POI\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n::\n\n    first_poi = poi_list[0]\n    first_article_id = first_poi.articles[0].id\n    print first_poi\n\nNow get all the data related to that Article\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n::\n\n    article = api.table('article').fetch(first_article_id).objects()\n    print article\n\nExamples\n--------\n\nCreate an API query object\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n::\n\n    api = HearPlanet()\n\nSpecify a search of the POI table\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n::\n\n    req = api.table('poi').search()\n\nAdd a query term, and search origin\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n::\n\n    req = req.term('Golden Gate')\n    req = req.location('San Francisco, CA')\n\nAdd a filter: only return articles in the Wikipedia channel\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n::\n\n    req = req.filters({'ch':'wikipedia'})\n\nAsk for only the first page (default is the first 10 objects)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n::\n\n    req = req.page(1)\n\nGet the return value as data or objects\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n::\n\n    objects = req.objects()  \n\nDo something with the objects\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n::\n\n    for poi in objects:\n        print poi.title\n\nOr, you can chain the requests all together\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n::\n\n    pois = api.table('poi').search().term('Golden Gate').location('San Francisco, CA').filters({'ch':'wikipedia'}).page(1).objects()\n\nUnit Tests\n----------\n\nUnit Tests are provided to ensure the driver is functioning as expected.\nThe unit tests also serve as examples of various API requests.\n\nYou can run the Unit Tests in test\\_hearplanet.py like this:\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n::\n\n    python test_hearplanet.py\n\nURL Encoding\n------------\n\nThe Python driver handles URL encoding, therefore all parameters passed\nto the driver should be in their un-encoded form.\n\n\n\n.. _Requests: http://docs.python-requests.org/en/latest/\n.. _API documentation: http://prod.hearplanet.com/api/2.0/documentation/",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "UNKNOWN",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "http://pypi.python.org/pypi/HearPlanetAPI/",
        "keywords": "HearPlanet API driver",
        "license": "UNKNOWN",
        "maintainer": null,
        "maintainer_email": null,
        "name": "HearPlanetAPI",
        "package_url": "https://pypi.org/project/HearPlanetAPI/",
        "platform": "UNKNOWN",
        "project_url": "https://pypi.org/project/HearPlanetAPI/",
        "project_urls": {
            "Download": "UNKNOWN",
            "Homepage": "http://pypi.python.org/pypi/HearPlanetAPI/"
        },
        "release_url": "https://pypi.org/project/HearPlanetAPI/0.1.1/",
        "requires_dist": null,
        "requires_python": null,
        "summary": "HearPlanet API driver",
        "version": "0.1.1"
    },
    "last_serial": 826428,
    "releases": {
        "0.1.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "eaa1a4694dcb843ba2cb2896c6fd3ec8",
                    "sha256": "714fb811a3cfa0f9010d35f44d1aa0667f028255e8238ea3e419ceaf7e7c4c16"
                },
                "downloads": -1,
                "filename": "HearPlanetAPI-0.1.1.tar.gz",
                "has_sig": false,
                "md5_digest": "eaa1a4694dcb843ba2cb2896c6fd3ec8",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 17217,
                "upload_time": "2013-07-27T21:31:37",
                "url": "https://files.pythonhosted.org/packages/63/30/4b4ec7356752063b4b7941edb6d0b507a04549b4696da69af2b1f8bf9f9c/HearPlanetAPI-0.1.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "eaa1a4694dcb843ba2cb2896c6fd3ec8",
                "sha256": "714fb811a3cfa0f9010d35f44d1aa0667f028255e8238ea3e419ceaf7e7c4c16"
            },
            "downloads": -1,
            "filename": "HearPlanetAPI-0.1.1.tar.gz",
            "has_sig": false,
            "md5_digest": "eaa1a4694dcb843ba2cb2896c6fd3ec8",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 17217,
            "upload_time": "2013-07-27T21:31:37",
            "url": "https://files.pythonhosted.org/packages/63/30/4b4ec7356752063b4b7941edb6d0b507a04549b4696da69af2b1f8bf9f9c/HearPlanetAPI-0.1.1.tar.gz"
        }
    ]
}