Examples
==========================

    On this page are several examples of querying the mPING API. For these examples we will use Python and the `Requests <http://docs.python-requests.org/en/latest/>`_ module. There are many REST client libraries available for many other languages.

.. contents::
   :local:

Example 1: Get all reports
===========================
    Here is the code to submit our request.::

        import requests
        import json

        # Set up our request headers indicating we want json returned and include
        # our API Key for authorization.
        reqheaders = {
            'content-type':'application/json',
            'Authorization': 'Token Your_API_Key'
            }

        url = 'http://mping.ou.edu/mping/api/v2/reports'
        response = requests.get(url,headers=reqheaders)


    Now we can check the status code and inspect the results. If request is successful call json() on the response object to decode the json response.::

        if response.status_code != 200:
            print 'Request Failed with status code %i' % response.status_code
        else:
            print 'Request Successful'
            data = response.json()
            # Pretty print the data
            print json.dumps(data,indent=4)

    Here is the example print output::

        Request Successful

    .. code-block:: json

        {
            "count": 258, 
            "next": "http://mping.ou.edu/mping/api/v2/reports?page=2", 
            "previous": null, 
            "results": [
                {
                    "id": 66681, 
                    "obtime": "2013-02-12T09:27:00Z", 
                    "category": "Rain/Snow", 
                    "description": "Rain", 
                    "description_id": 3, 
                    "geom": {
                        "type": "Point", 
                        "coordinates": [
                            -97.1462239, 
                            33.1970531
                        ]
                    }
                }, 
                {
                    "id": 66682, 
                    "obtime": "2013-02-12T09:42:00Z", 
                    "category": "Rain/Snow", 
                    "description": "Mixed Ice Pellets and Snow", 
                    "description_id": 10, 
                    "geom": {
                        "type": "Point", 
                        "coordinates": [
                            -101.86909, 
                            33.50854
                        ]
                    }
                }, 
                {
                    "id": 66683, 
                    "obtime": "2013-02-12T09:29:00Z", 
                    "category": "Rain/Snow", 
                    "description": "Sleet/Ice Pellets", 
                    "description_id": 7, 
                    "geom": {
                        "type": "Point", 
                        "coordinates": [
                            -101.8621469, 
                            35.14763472
                        ]
                    }
                }, 
                {
                    "id": 66684, 
                    "obtime": "2013-02-12T09:48:00Z", 
                    "category": "Rain/Snow", 
                    "description": "Drizzle", 
                    "description_id": 5, 
                    "geom": {
                        "type": "Point", 
                        "coordinates": [
                            -101.86924, 
                            33.50853
                        ]
                    }
                }, 


Example 2: Filter by Category
===============================
    We will now make a similar request but this time we will add a query parameter to filter on Hail reports only::

        import requests
        import json

        reqheaders = {
            'content-type':'application/json',
            'Authorization': 'Token Your_API_Key'
            }

        reqparams = {
            'category':'Hail'
        }

        url = 'http://mping.ou.edu/mping/api/v2/reports'
        response = requests.get(url, params=reqparams, headers=reqheaders)


    The only difference from the first example is the reqparams we have added to the request.  Let's print out the url to see what this looks like.::

        print response.url

        http://mping.ou.edu/mping/api/v2/reports?category=Hail

    Notice it added on ?category=Hail to the end of the url.