HTTP Status Codes

- 200 OK: normal response code for a succeeded call.
- 400 Bad Request: your request is invalid, and we'll return an error message that tells you why. This is the status code returned if you've exceeded the rate limit.
- 401 Not Authorized: Your API key is probably invalid.
- 403 Forbidden: we understand your request, but are refusing to fulfill it.  An accompanying error message should explain why.
- 404 Not Found: either you're requesting an invalid URI or the resource in question doesn't exist (ex: no such user).
- 500 Internal Server Error: An error occured on our side
- 502 Bad Gateway: returned if the service is down or being upgraded.
- 503 Service Unavailable: the servers are up, but are overloaded with requests.  Try again later.

Errors

Errors are returned with the following variables. They can be JSON/XML, depending on chosen format.
- request: URL of the request
- error: explained error message

Rate Limiting

There are no rate limits in place at the moment, but this van and probably will change in the future.

Encoding

All parameters should be UTF-8 encoded and HTML chars should be entity-encoded to prevent Cross-Site Scripting attacks for web-embedded consumers.
All return variables are UTF-8 encoded and are entity-encoded to prevent Cross-Site Scripting attacks for web-embedded consumers

API functions

Create:

Creates a new Spot based on longitude/latitude coordinates or an address.
URL: http://spot2.be/api/create/format/[format]
Return formats: xml, json
Method(s): POST

Parameters:
- api_key: API key provided by Spot2.be.
- longlat: When a longitude/latitude coordinate is given, the address attributes are being ignored. Please provide in the following format: 52.364856,4.902177
- street: including the street number
- city:
- country: use the full country name, so United States instead of US
- display_name (Optional): Title of the Spot
- permalink (Optional): Nice url for the spot. When a permalink is given, no random permalink will be generated
- description (Optional): Description of the Spot

Return variables:
- permalink: Can be different from given permalink when given permalink already exists

Show

Retrieve the details of a given Spot by permalink. If a range is provided we will also return POI's withing the given range.
URL:
http://spot2.be/api/show/format/[format]/api_key[api_key]/permalink/[permalink]/range/[range]
Return formats: xml, json
Method(s): GET

Parameters:
- api_key: API key provided by Spot2.be. (See below)
- permalink

Return variables:
- longlat: Longitude/Latitude coordinate
- street:
- city
- country
- display_name: The title of the Spot
- description: Description of the Spot
- view_count: Times the Spot is viewed.

Need support or a personal API key?

You can get a API key by visiting our API Key request page and filling in some basic details.

For help or info, you can contact:
Timan Rebel, timan@spot2.be, twitter.com/timanrebel
Mathys van Abbe, mathys@spot2.be, twitter.com/mathys