Skip to main content

An easy-to-use wrapper for the Open311 API

Project description

An updated [Open311 API](http://wiki.open311.org/GeoReport_v2) Python wrapper that was built to be as absolute user-friendly and easy-to-use as possible. Many of the design decisions made will reflect these qualities.

Installation

This is still a work in progress, but you can git clone this repo and run python setup.py install to check out the current progress.

Settings

### API Key

If you have an Open311 API key that you always intend to use, rather than initializing the Three class with it each time, you can set an OPEN311_API_KEY environment variable on the command line.

export OPEN311_API_KEY=”MY_API_KEY”

Otherwise, you can initialize the class with your API key and endpoint.

>>> from three import Three
>>> t = Three('api.city.gov', api_key='my_api_key')

### HTTPS

By default, Three will configure a URL without a specified schema to use HTTPS.

>>> t = Three('api.city.gov')
>>> t.endpoint == 'https://api.city.gov/'
True

### Format

The default format for the Three wrapper is JSON – although not all [Open311 implementations support it](http://wiki.open311.org/GeoReport_v2#Format_Support). This is done mainly for easy-of-use (remember, that’s the over-arching goal of the Three wrapper). You can, however, specifically request to use XML as your format of choice.

>>> t = Three('api.city.gov', format='xml')
>>> t.format == 'xml'
True

Usage

### Configure

After you’ve initialized your Three class, you can readjust its settings with the configure method. You can also switch back to the orgininal settings with the reset method.

>>> from three import Three
>>> t = Three('api.city.gov', api_key='SECRET_KEY')
>>> t.services()
{'service': 'data'}
>>> t.configure('open311.sfgov.org/dev/V2/', format='xml'
...             api_key='SF_OPEN311_API_KEY')
>>> t.services()
{'SF': {'service': 'data'}}
>>> t.configure(api_key='ANOTHER_API_KEY')
>>> # Switch back to original settings.
... t.reset()

### Discovery

In order to use the [Open311 service discovery](http://wiki.open311.org/Service_Discovery), simply invoke the discovery method.

>>> t = Three('api.city.gov')
>>> t.discovery()
{'service': {'discovery': 'data'}}

Sometimes, however, service discovery paths differ from service and request URL paths – in which case you can pass the specified URL to the discovery method as an argument.

>>> t.discovery('http://another.path.gov/discovery.json')

### Services

To see the available services provided by an Open311 implementation, use the services method.

>>> t = Three('api.city.gov')
>>> t.services()
{'all': {'service_code': 'info'}}

You can also specify a specific service code to get information about.

>>> t.services('033')
{'033': {'service_code': 'info'}}

### Requests

To see available request data, use the requests method.

>>> t = Three('api.city.gov')
>>> t.requests()
{'all': {'requests': 'data'}}

You can also specify a specific service code.

>>> t.requests('123')
{'123': {'requests': 'data'}}

Other parameters can also be passed as keyword arguments.

>>> t.requests('456', status='open')
{'456': {'open': {'requests': 'data'}}}

### Request

If you’re looking for information on a specific Open311 request (and you have it’s service code ID), you can use the request method.

>>> t = Three('api.city.gov')
>>> t.request('12345')
{'request': {'service_code_id': {'12345': 'data'}}}

### Post

Sometimes you might need to programmatically create a new request, which is what the post method can be used for. NOTE: the Open311 spec states that all POST service requests [require a valid API key](http://wiki.open311.org/GeoReport_v2#POST_Service_Request).

>>> t = Three('api.city.gov', api_key='SECRET_KEY')
>>> t.post('123', name='Zach Williams', address='85 2nd St',
...        description='New service code 123 request.')
{'new': {'request': 'created'}}

### Token

Each service request ID can be tracked with a temporary token. If you need to find the service request ID and have the request’s token, you can use the token method.

>>> t = Three('api.city.gov')
>>> t.token('12345')
{'service_request_id': {'for': {'token': '12345'}}}

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

three-0.2.tar.gz (5.2 kB view hashes)

Uploaded source

Built Distribution

three-0.2-py2.7.egg (10.1 kB view hashes)

Uploaded 2 7

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page