API

Though we provide links to let individuals download their OpenPaths data in a variety of formats, some people (including us) are interested in programmatic access. The API is based on OAuth, which is emerging as a standard for secure data access. Initially, OpenPaths is only allowing you to access your own data (in the future, you may be able to grant access to others, ie researchers). For this reason, we are using "2-legged" OAuth. There's a nice description of why this is appropriate.

The disadvantage of OAuth is that it can be very confusing. We've tried to keep it as dirt-simple straightforward as possible.

1. Get your keys

Two-legged OAuth authenticates each HTTP request with an "access key" and a "secret key", which can be found on your data page when you log into your account. Keep these keys secure. If you share these keys with others, they will have access to your data. However, note that you can reset your secret key at any time to keep it secure.

2. Choose your parameters

The last 2000 points in a dataset are available through the API. Within that constraint, you can use three optional parameters to narrow it down: start_time, end_time, and num_points.

start_time and end_time are specified as UNIX timestamps, and are inclusive. If the time period specified extends further back than the last 2000 points, the server will respond with an error.

Without start_time and end_time, the API will return the last 100 points by default. You can set the number of points returned by specifying the num_points parameter, which may be from 0-2000.

3. Access projects

Coming soon

4. Make your request

API requests must be signed with the OAuth HMAC-SHA1 method. This means you'll have oauth_consumer_key, oauth_version, oauth_nonce, oauth_timestamp, oauth_body_hash, oauth_signature_method, and the resulting oauth_signature included in your request. That sounds complicated, but there are libraries to get this going for you.

The url for all requests is https://openpaths.cc/api/1 The API is currently version 1, which is indicated with the trailing number.

Example

The following example is in Python and requires oauth2. (Let us know if you implement it in another language, so we can include it here.)

            
#!/usr/bin/env python        

import oauth2, time, urllib, urllib2, json

ACCESS = "YOURACCESSKEY"
SECRET = "YOURSECRETKEY"
URL = "https://openpaths.cc/api/1" 

def build_auth_header(url, method):
    params = {                                            
        'oauth_version': "1.0",
        'oauth_nonce': oauth2.generate_nonce(),
        'oauth_timestamp': int(time.time()),
    }
    consumer = oauth2.Consumer(key=ACCESS, secret=SECRET)
    params['oauth_consumer_key'] = consumer.key 
    request = oauth2.Request(method=method, url=url, parameters=params)    
    signature_method = oauth2.SignatureMethod_HMAC_SHA1()
    request.sign_request(signature_method, consumer, None)
    return request.to_header()

# GET data (last 24 hours)
now = time.time()
params = {'start_time': now - 24*60*60, 'end_time': now}    # get the last 24 hours
query = "%s?%s" % (URL, urllib.urlencode(params))
print(query)
try:
    request = urllib2.Request(query)
    request.headers = build_auth_header(URL, 'GET')
    connection = urllib2.urlopen(request)
    data = json.loads(''.join(connection.readlines()))
    print(json.dumps(data, indent=4))
except urllib2.HTTPError as e:
    print(e.read())    
    

5. Use your data

The API returns JSON. You will get an array of objects — each one comprises a location object with lat, lon, and alt data and a timestamp. You will also see metadata on how the record was generated (if applicable), including the device model, its operating system version, and the version of the OpenPaths mobile app. Requests for project data will also include a participant identifier for each entry.

    
[
    {
        "lon": -73.99093,
        "lat": 40.751453, 
        "alt": 0.0,
        "t": 1308274880,
        "device": "iPhone3,1", 
        "os": "4.3.2",
        "version": "1.0"
    } 
]    
    

6. POST new data

The API works in both directions — in addition to downloading your location data, you may submit it as well. Everything works the same as above, except we'll be sending a POST request instead of GET. The body of the request should be a JSON object that is an array of points, formatted just as you'd receive it in a GET request, with the exception of the "device", "os", and "version" fields (these are set automatically to indicate that the points were pushed to OpenPaths through the API). Note that you can contribute only to your personal dataset through the API, points cannot be uploaded to projects directly.

Example

       
...
            
# POST data  
now = time.time()
points = [  {'lat': 40.75145, 'lon': -73.99093, 'alt': 0.0, 't': now},
            {'lat': 40.65125, 'lon': -74.89093, 'alt': 0.0, 't': now}
            ]
# geo point data is formatted as a json string            
params = {'points': json.dumps(points)}
try:
    request = urllib2.Request(URL)
    request.headers = build_auth_header(URL, 'POST')
    connection = urllib2.urlopen(request, urllib.urlencode(params))
    data = json.loads(''.join(connection.readlines()))
    print(json.dumps(data, indent=4))
except urllib2.HTTPError as e:
    print(e.read())