What is the Oil Reporter API?
The Oil Reporter API contains a series of methods for obtaining data through standard HTTP requests. This allows Oil Reporter to be integrated with just about any application that can connect to the web.
Sign Up
You can get an API key by signing up for one here.
Table of Contents
- Data Structure
- Create a New Report
- Create a New Report Session
- Add Metadata to Report Session
- Add Metadata to Report
- Add Media to Report
- Retrieve a List of Reports
- Retrieve a List of Reports from Report Session
- Retrieve a List of Reports by Organization
Data Structure
The structure of a report is below.
- id (integer, read-only)
- organization_pin (integer, optional)
- report_session_id (integer, optional)
- oil (integer, 0-10)
- wetlands (integer, 0-10)
- description (text)
- wildlife (text)
- latitude (float)
- longitude (float)
- created_at (datetime)
- media (hash/binary)
When parsing the results of a call to list, the media property
is a hash with the fields tiny, thumb and medium each of which
is a string corresponding to the URL where the image is located.
If media has not been set then the value is null.
On a call to update to upload a photo, then media accepts a binary stream.
- meta (string key value pair)
Can only create this when updating a report or adding media.
See documentation below for a good explanation on how to add metdata.
Create a New Report
Allows you to create a new report. This request needs a unique device identifier (device_id).
curl -d "api_key=YOUR_API_KEY&latitude=29.964639&longitude=-90.067763&oil=5&wetlands=7&description=Distressed%20Wildlife&device_id=UNIQUE_DEVICE_ID" http://oilreporter.org/reports
Returns {"id":8}
Create a New Report Session
Allows you to create a new report session to use to group a batch of reports.
curl -d "api_key=YOUR_API_KEY" http://oilreporter.org/report_sessions
Returns {"id":26}
Add Metadata to Report Session
Allows you to add as many metadata elements to your report session. You need the ID of the report you created to be able to call this url. Meta parameters can use any key and any value. Both keys and values are stored as strings. You can pass as many metadata items as you want. In the example below we are adding two meta values. The first one has a key of my_key_1 with a value of custom value. The other meta element has a key of extra_url with a value of oilreporter.org.
curl -d "api_key=YOUR_API_KEY&meta[my_key_1]=custom%20value&meta[extra_url]=oilreporter.org" -X PUT http://oilreporter.org/report_sesions/8 Returns empty text and an HTTP status code of 200
Add Metadata to Reports
Allows you to add as many metadata elements to your report. You need the ID of the report you created to be able to call this url. Meta parameters can use any key and any value. Both keys and values are stored as strings. You can pass as many metadata items as you want. In the example below we are adding two meta values. The first one has a key of my_key_1 with a value of custom value. The other meta element has a key of extra_url with a value of oilreporter.org.
curl -d "api_key=YOUR_API_KEY&meta[my_key_1]=custom%20value&meta[extra_url]=oilreporter.org" -X PUT http://oilreporter.org/reports/8 Returns empty text and an HTTP status code of 200
Add Media to Report
Allows you to add media to an existing report. You need the ID of the report you created to be able to call this url. You may also pass metadata in this call as well (see above).
curl -X PUT -F "media=@seagull.jpg" http://oilreporter.org/reports/8?api_key=YOUR_API_KEY Returns empty text and an HTTP status code of 200
Retrieve a List of Reports
Allows you to retrieve a list of reports.
curl http://oilreporter.org/reports.json?api_key=YOUR_API_KEY
Returns
[
{ "id": 8,
"oil": 5,
"wetlands": 7,
"description": "Distressed Wildlife",
"wildlife": "Dead",
"latitude":"29.9646",
"longitude": "-90.0678",
"created_at": "2010-05-13T19:29:54Z",
"report_session_id": null,
"media": { "tiny":"http://s3.amazonaws.com/oilreporter_production/medias/7/tiny.jpg?1273722135",
"thumb":"http://s3.amazonaws.com/oilreporter_production/medias/7/thumb.jpg?1273722135",
"medium":"http://s3.amazonaws.com/oilreporter_production/medias/7/medium.jpg?1273722135" },
"meta": { "my_custom_key": "my custom value",
"another_item": "another value"}
}
]
Retrieve a List of Reports by Report Session
Allows you to retrieve a list of reports with a specific report session id
curl http://oilreporter.org/report_sessions/REPORT_SESSION_ID/reports.json?api_key=YOUR_API_KEY
Returns
[
{ "id": 8,
"oil": 5,
"wetlands": 7,
"description": "Distressed Wildlife",
"wildlife": "Dead",
"latitude":"29.9646",
"longitude": "-90.0678",
"created_at": "2010-05-13T19:29:54Z",
"report_session_id": 26,
"media": { "tiny":"http://s3.amazonaws.com/oilreporter_production/medias/7/tiny.jpg?1273722135",
"thumb":"http://s3.amazonaws.com/oilreporter_production/medias/7/thumb.jpg?1273722135",
"medium":"http://s3.amazonaws.com/oilreporter_production/medias/7/medium.jpg?1273722135" },
"meta": { "my_custom_key": "my custom value",
"another_item": "another value"}
}
]
List reports by organization
Allows you to retrieve a list of an organization's reports
curl -d "api_key=YOUR_API_KEY" http://oilreporter.org/organizations/1001
[
{ "id": 8,
"oil": 5,
"wetlands": 7,
"description": "Distressed Wildlife",
"wildlife": "Dead",
"latitude":"29.9646",
"longitude": "-90.0678",
"created_at": "2010-05-13T19:29:54Z",
"report_session_id": null,
"media": { "tiny":"http://s3.amazonaws.com/oilreporter_production/medias/7/tiny.jpg?1273722135",
"thumb":"http://s3.amazonaws.com/oilreporter_production/medias/7/thumb.jpg?1273722135",
"medium":"http://s3.amazonaws.com/oilreporter_production/medias/7/medium.jpg?1273722135" },
"meta": { "my_custom_key": "my custom value",
"another_item": "another value"}
}
]
