Get API base URL for given area
There will be multiple Waste Map servers in the world. For example, Lithuania had its own server for Lithuanian 2011 cleanup, and LDIW international team has a Global Waste Mapping server covering all areas not covered by other servers. This function allows a mapping application to find out which server to talk to for a given area. This function is only available in the Global Waste Mapping server, because only this server is knows about all other servers.
URL: GET/POST http://api.letsdoitworld.org/?q=get-api-base-url.json
Response formats: JSON
Requires Authentication: no
Parameters:
- lat - required; WGS84
- lon - required; WGS84
Response:
{
api_base_url:'http://api.mesdarom.lt/?q=',
safe_bbox:'-122.497790,37.730385,-122.380087,37.812331'
}
The safe_bbox field is a bounding box (min_lon,min_lat,max_lon,max_lat in WGS84) around requested location where API base URL is the same. In other words, after getting a response from this function, it is not necessary to call it again for locations within returned safe_bbox. However, sometimes servers are added/removed/changed (e.g. a new country joins LDIW), thus clients should not cache it permanently.
Note that returned api_base_url may or may not include a query portion ('?'). This requires correct handling for functions needing GET parameters: if api_base_url includes '?', then additional GET parameters must be appended to URL using '&'; otherwise, the first GET parameter must be appended using '?'.
Get server-specific Waste point fields
Some WP fields are server-specific. For example, Slovenia in 2010 had "terrain type" field, which Estonia in 2008 did not have. Each server can configure arbitrary number of such fields, and using this function clients can learn what these fields are and what editing controls to display for them.
API users (=you!) do not have to know or care at all about the semantic meaning of fields, i.e. is it size of the WP, or composition, or something else. For API user these are just fields, and this function describes these fields in terms of type, label etc.
All possible field attributes are shown in example response below. Fields are returned in their suggested order on WP edit form, and there may be 'type':'begin_section' entries between them to describe a group of fields that follow it. All entries have mandatory type and label attributes, other attributes are optional. All textual attributes are in Unicode (i.e. not limited to ASCII).
'type':'float', 'type:integer' and 'type':'text' fields may have allowed_values attribute, which is a list of value-label pairs to be displayed as drop-down list or similar UI element.
'type':'float' and 'type:integer' fields may have a similar typical_values attribute, which can be used in touchscreens and other UIs where selecting from a list of predefined values is much easier than typing in a number.
Returned data may or may not include volume field. If it does not include volume field, then WP volume is not supposed to be filled by mapper, and is calculated in server side from other fields instead.
URL: GET <api_base_url>/waste-point-extra-fields.json
Response format: JSON
Requires Authentication: no
Parameters:
- language_code - (optional, string) RFC 4646 compliant language code (e.g. 'es') for label, edit_instructions, allowed_values, typical_values. If language_code is unrecognised or missing, then server language is used
Response:
[ {
type:'float',
field_name:'volume',
suffix:'m\u00b3',
min:0,
max:100000,
typical_values:[[0.3,'0.3'],[1,'1'],[3,'3'],[10,'10'],[30,'30'],[100,'100'],[300,'300'],[1000,'1000']] ,
label:'Volume of waste',
edit_instructions:'Size of a plastic grocery bag is 0.3m\u00b3, size of car is 5m\u00b3',
},
{
type:'integer',
field_name:'nr_of_tires',
suffix:'tires',
min:0,
max:100000,
typical_values:[[0,'no'],[1,'1'],[3,'3'],[10,'10'],[30,'30'],[100,'100'],[300,'300'],[1000,'1000']] ,
label:'Number of tires',
edit_instructions:'Count approximate number of tires among waste',
},
{
type:'text',
field_name:'description',
suffix:'',
max_length:2000,
label:'Description',
edit_instructions:'Write notes about Waste point',
},
{
type:'begin_section',
label:'Access to waste',
},
{
type:'text',
field_name:'terrain_type',
suffix:'',
allowed_values:[['M','mountainous'],['F','flat'],['W','wet']],
label:'Terrain type',
edit_instructions:'Select terrain type near Waste point',
},
{
type:'boolean',
field_name:'accessible_by_car',
suffix:'',
label:'Is accessible by car',
edit_instructions:'Check if waste is accessible by car',
},
]
Get Waste point details as HTML
This function is needed because server-specific WP fields do not have universal interpretation nor display rules. Web-based Waste Map gets by without this function, because each server has its own map which can be customised to display such fields; but mobile apps are not so easy to customise, and ideally one mapper could map in several countries using the same app.
Returned HTML does not include data for lat, lon, cleaned_by_mapper fields. It does include photos, along with photo attribution and link to original (which may be mandatory to display for some photo licenses). The HTML has fixed HTML class names, DIVs and SPANs, so it can be styled with CSS.
URL: GET <api_base_url>/wp/<waste_point_or_cluster_id>.html
Response format: HTML snippet in UTF-8 encoding
Requires Authentication: no
Parameters:
- max_width - (optional, in pixels; default 500) Maximum width of desired HTML. This is important for photos
- language_code - (optional, string) RFC 4646 compliant language code, e.g. 'es'. If language_code is unrecognised or missing, then server language is used
Response:
<div><a href="http://www.flickr.com/photos/26209306@N00/3194493333"><img src="http://farm4.static.flickr.com/3337/3194493333_9ba5724946.jpg" width="320" height="240"/></a></div><div>Photo by <a href="http://www.flickr.com/people/26209306@N00/"><b>Pedalofilo</b></a>, found from Flickr</div><hr>
<span class='volume'>
<div class='field_label'>Volume:</div>
<div class='value'>7m³</div>
</span>
<span class='id'>
<div class='field_label'>ID:</div>
<div class='value'>138678</div>
</span>
<hr>
<span class='composition'>
<div class='field_label'>Composition:</div>
<div class='value composition_paper'>80% paper</div>
<div class='value composition_other'>20% other</div>
</span>
Login with username/password
URL: POST <api_base_url>/user/login.json
Response formats: JSON
Requires Authentication: no
Parameters:
- username - (required, string) Username to log in as
- password - (required, string) Password of the user
Successful response has HTTP status 200, and has session_name and sessid attributes in response body in JSON format. To authenticate subsequent API requests, send a cookie <session_name>=<sessid> along with requests.
Unsuccessful response is indicated with HTTP status code, e.g. "401 Unauthorized" if username/password are incorrect.
Example of successful response:
{
"sessid":"d85p1218g4rl6nkulpntu3sll3",
"session_name":"SESS08d15a4aef553492d8971cdd5198f314"
}
Add/modify/confirm Waste point
Add a new WP or modify an existing WP. When adding a new WP, then if a WP exists very close to this location, the server automatically modifies existing WP instead of adding a new one. Only individual WPs (not clusters) can be added/modified.
If this method returns HTTP error 400, this may be because of field validation failure, so give the user the option to re-edit inputs. Detailed error description appears in HTTP error text accompanying the numeric code.
To confirm that data of an existing WP is still correct (WP is marked in correct place and size, photo etc are more or less correct), do the "modify/confirm existing WP" part of this operation without any POST parameters.
Response is the full data of this WP after this add/modify/confirm operation.
URL: POST <api_base_url>/wp.json (add new WP)
URL: POST <api_base_url>/wp/<waste_point_id>.json?_method=PUT (modify/confirm existing WP, if <api_base_url> does not contain '?')
URL: POST <api_base_url>/wp/<waste_point_id>.json&_method=PUT (modify/confirm existing WP, if <api_base_url> contains '?')
Response formats: JSON
Requires Authentication: optional, with cookie (see Login with username/password function); if request has non-empty but invalid cookie, HTTP 401 response is returned
Parameters:
- client_id - (optional, string) semi-uniquely identifies the phone/client for anti-abuse purposes (i.e. malicious anonymous mapper draws shapes on map using waste points; using client_id they could be blocked)
- lat - required when adding a new WP, otherwise optional; WGS84
- lon - required when adding a new WP, otherwise optional; WGS84
- cleaned_by_mapper - (optional, integer) nonzero values indicate that the WP was cleaned by mapper. The rest of WP fields represent the WP before cleaning. The Waste Map database will record the state before cleaning, and also the state after cleaning (with zero volume). The latter is returned as JSON response data.
- photo_file_1, photo_file_2, photo_file_3, ... - (optional) JPG or PNG files; each file value is either a string, or file attachment as specified in RFC2388. When modifying an existing WP, photos are added to the list of photos of this WP; it is not possible to replace or delete existing photos via API.
- Optional parameters for server-specific WP fields from Get server-specific Waste point fields function. If any server-specific fields are present in request (even with empty values), then data for all server-specific fields is overwritten in WP, and data for missing/empty server-specific fields is deleted. Boolean fields accept values 0 and 1.
Response:
{
wp:{
id:'3134',
description:'lots of tires',
lat:40.7192,
lon:-74.0103,
nr_of_tires:50,
volume:30.5,
composition_dangerous:90,
composition_other:10,
composition_construction:0,
composition_biodegradable:0,
composition_large:0,
photos: "YWYz:334:500 61qZ:400:400",
}
}
List waste points in given area
Returns a list of WPs/clusters in specified area.
If more than max_results WPs are in this area, they are combined in clusters as needed. Thus returned data can contain a mixture of clusters and individual WPs. Data for each cluster is aggregate of WPs the cluster represents, and also includes a nr_of_nodes field indicating the number of WPs it represents.
Each WP/cluster has the following fields:
- id - string, not empty
- lat - float, not empty. WGS84
- lon - float, not empty, WGS84
- photos - optional
- nr_of_nodes - non-empty for clusters, empty/missing for individual WPs
- optional server-specific fields, as described by Get server-specific Waste point fields function. Composition fields are exceptions here: in JSONvalues returned by API, they are always provided as 0..100 percentage values, one per composition type, regardless of how they are specified in Get server-specific Waste point fields function. This exception concerns only API function return values, not input values provided to API.
- volume - float, optional, in cubic meters. If WP size is known, then this field is always non-empty even if it is not among server-specific fields
- cleaned_by_mapper - integer or empty string. Nonzero values indicate that the WP was cleaned by mapper; in this case, volume is usually also zero.
- distance_meters - float (only if nearest_points_to parameter is set)
URL: GET/POST <api_base_url>/waste_points.{json,csv,kml}
Response formats: JSON, CSV (with header row), KML (only CSV is currently implemented)
Requires Authentication: no
Parameters:
- BBOX - (optional) bounding box, like in KML (min_lon,min_lat,max_lon,max_lat in WGS84): -122.497790,37.730385,-122.380087,37.812331
- max_results - max nr of results (optional, default 10)
- nearest_points_to - (optional) coordinates (lon,lat in WGS84): "-74,30". If set, then returns individual WPs (not clusters) nearest to the coordinates given, and also adds a distance_meters field to results.
Response (truncated):
[
{
id:'3134',
description:'lots of tires',
lat:40.7192,
lon:-74.0103,
nr_of_tires:50,
volume:30.5,
composition_dangerous:90,
composition_other:10,
composition_construction:0,
composition_biodegradable:0,
composition_large:0,
photos: "YWYz:334:500 61qZ:400:400",
cleaned_by_mapper:1,
},
{
id:'c233',
nr_of_nodes:17,
volume:500.5,
composition_dangerous:90,
composition_other:10,
composition_construction:0,
composition_biodegradable:0,
composition_large:0,
...
},
...
]
