Spottingmode API response formats
The default response format is in a json string. Json is text based, data-interchange format. It is language independent but most modern day weblanguages have build in support to encode and decode json strings.
Alternatively, most methods also provide the option to return the data in xml format. The response format can be requested through the url as the third parameter. 'json', 'xml' or 'csv' (see below), which will always default to json if the method does not support the requested response format. Also an invalid response format will default to json.
https://www.spottingmode.com/api/{entry_point}/{method_name}/{response_format}/?parameter=value
For both json and xml responses, the response will consist of sections for each data section in the resultset. Each section in turn will consist of an array with elements for each record. Check the documentation for the exact sections that each method will return. For xml furthermore, all data is nested in a root element.
Response examples
Json example:
{"locations":[
{
"url": "http://www.spottingmode.com/wro/location/2424/",
"location_name": "Antwerpen - Stampe en Vertongen Museum",
"description": "Various",
"lat": "51.18963623",
"lng": "4.45144606"
},{
"url": "http://www.spottingmode.com/wro/location/2426/",
"location_name": "Balen",
"description": "CM.170 (not clearly visible)",
"lat": "51.18441010",
"lng": "5.19352913"
}]
}Xml example:
<?xml version="1.0" encoding="UTF-8"?>
<root>
<locations>
<location>
<url>http://www.spottingmode.com/wro/location/2424/</url>
<location_name>Antwerpen - Stampe en Vertongen Museum</location_name>
<description>Various</description>
<lat>51.18963623</lat>
<lng>4.45144606</lng>
</location>
<location>
<url>http://www.spottingmode.com/wro/location/2426/</url>
<location_name>Balen</location_name>
<description>CM.170 (not clearly visible)</description>
<lat>51.18441010</lat>
<lng>5.19352913</lng>
</location>
</locations>
</root>Methods using pagination
When the response of a method could contain a resultset with too many records (hundreds if not thousands), the resultset will be split into multiple parts. This is generally referred to as pagination and it basically cuts the results up into fixed size sets or pages. Methods in the Spottingmode API that use pagination will always have the optional parameter 'start' and in many cases the optional parameter 'num'. Start defines the first record to be retrieved in the call (starting at 0!), while num defines the number of records to be retrieved. Note that although any integer value for num is accepted, all methods will have a maximum value, usually 500.
The pagination parameters as given will always be returned in the response as well, together with a 'totalrows' value. This totalrows value denotes how many records would have been returned if no pagination was used. The three values together (start, num and totalrows) are sufficient to create a full navigation element for all pages that result from this call.
Pagination parameters are always added to the section it belongs to, in a separate element.
Json pagination example:
{"locations":[
{
"url": "http://www.spottingmode.com/wro/location/2424/",
"location_name": "Antwerpen - Stampe en Vertongen Museum",
"description": "Various",
"lat": "51.18963623",
"lng": "4.45144606"
},
...
{
"pagination":{
"start": 0,
"num": 100,
"totalrows": 351}
}]
}Xml pagination example:
<?xml version="1.0" encoding="UTF-8"?>
<root>
<locations>
<location>
<url>http://www.spottingmode.com/wro/location/2424/</url>
<location_name>Antwerpen - Stampe en Vertongen Museum</location_name>
<description>Various</description>
<lat>51.18963623</lat>
<lng>4.45144606</lng>
</location>
...
<pagination>
<start>0</start>
<num>100</num>
<totalrows>351</totalrows>
</pagination>
</locations>
</root>Response in csv format
A limited number of methods also support a csv response. The csv response will be pushed out as a downloadable file and is specifically provided to allow a call to the API from the browser. The csv file can then be used to upload to Google Maps for example.
The use of downloadable csv files is limited to those methods providing map based data. This support is provided to allow webmasters with limited programming or scripting skills to use the Spottingmode API to add map data to their sites with as little effort as possible.
Error responses
Requests to the Spottingmode API can fail for a number of reasons, including (but no limited to): invalid method name, failed authentication, call throttling limit reached or missing parameters. Whatever the reason for a requests to fail, the API will return an specific error response. This response will include an error code and message. Furthermore, the API always sends back an HTTP header containing an HTTP status code. When the request was handled successfully the status code will be 200 (OK), if it failed it will be 400 (bad request), 403 (forbidden) or 500 (internal server error).
Error responses will always be in the response format requested (json or xml), but not for csv. Since pushing a downloadable file is not possible after an HTTP status code of 400, 403 or 500, the response will be sent in json format. It is therefore imperative that you check the HTTP status code when calling an API method with csv response programatically. Do not simply expect the file to be pushed.
Json error response example:
{"error": {
"code": "1",
"description": "The requested method does not exist in this API. Please check the manual."
}}Xml error response example:
<?xml version="1.0" encoding="UTF-8"?>
<root>
<errors>
<error>
<code>1</code>
<description>The requested method does not exist in this API. Please check the manual.</description>
</error>
</errors>
</root>Empty datasets are not considered errors. Requesting for example all wrecks and relics locations in a country that does not exist, will return a valid response. The response, however, will consist of an empty section. Always make sure to allow your code to process empty sets correctly.