Concepts

JSON

Most GET requests return JSON.  The only GET requests that don't return JSON are requests ending in .gpx.

JSON stands for Javascript Object Notation.

JSONP

JSONP or "JSON with Padding" can be returned from any request that returns JSON.  This can be done by adding a callback parameter with the name of you callback function.  This can be used for Cross-Origin Resource Sharing.

GPX

You can append ".gpx" to GET requests made to the geocache resource. If you do, the response will be an XML file instead of JSON.

GPX is an open standard for storing and sharing waypoint, track, and route information using XML files. The standard has been expanded to hold information specific to geocaching. The gpx files from Opencaching follow the standard defined in the GPX schema, the Groundspeak extension and the OpenCaching extension.

Text

POST requests respond with JSON and/or plain text.

If there was an error, an error message will be returned.

GET request also respond with a text description if the request encountered an error.

Dates/Times

All dates or times are returned is the number of milliseconds since January 1, 1970. Or, Unix time * 1000.

Date can be sent to the API in Unix time or Unix time * 1000.

Status Codes

Responses will always include an appropriate HTTP status code.

200 = Success.

400 = You provided invalid parameters.

413 = The response would be bigger than the maximum size you asked for.

500 = Something went wrong on our end. If you get this repeatedly, please report the problem to us.