Getting Started

The OpenCaching.com API allows you to query all the data stored in the OpenCaching.com database.  You can even use the API to authenticate users to update and write data to the database.  The first step to using the API is to request a Developer Key. 

Developer Key

To access the OpenCaching.com API you need a developer key. 

Terms of Use

The legal agreement you must agree to follow before accessing the API.

Concepts

General ideas behind how OpenCaching.com and the OpenCaching.com API work.

Creative Commons

All public, user submitted content in the OpenCaching.com database is licensed under the Creative Commons Attribution-ShareAlike License (CC-by-sa).

REST Web Service Interface

The OpenCaching.com API is offered through a REST interface. Object can be read, written to, and edited using standard HTTP requests.

Return Types

Most requests will return JSON.  GET requests ending with ".gpx" return XML.  Some POST requests will return plain text.

OX Codes

OX Codes are unique identifiers assigned to geocaches.

Geocache Ratings

Geocaches are rated based on difficulty, terrain, size, and awesomeness.

Media Resources

OpenCaching artwork and logos.  Please read through our trademark license and Usage Guidelines before using any of the OpenCaching resources.

Authentication

User authentication and authorization to OpenCaching.com are done through OAuth. An application that wants to make requests that require a user be logged-in will have to have that user sign in using the OAuth protocol.

Introduction to OAuth

Introduction to OAuth and how to get an OAuth consumer key and secret

Authenticating with OAuth

OAuth Authentication is done in three steps:

  1. The Consumer obtains an unauthorized Request Token.
  2. The User authorizes the Request Token.
  3. The Consumer exchanges the Request Token for an Access Token.

Read

HTTP GET requests are made to read data from OpenCaching.com.  Parameters can be used to filter the data that is returned.

Geocache

Returns a single geocache by geocache_id or query for a list of geocaches using any combination of parameters available.  Geocaches can be returned as JSON or as a GPX file.

Log

Returns a list of logs filtered by parameters or a single log matching the specified log_id.

User

Returns information about a single user that has the specified user_id or display_name.

Tag

Tags can be used to further define a geocache.  Returns a list of tags ordered by how many geocaches are tagged with that tag.

Series

A series is a collection of geocaches that are related to each other.  This API call returns a single series by series_id or can return a list of series.

Saved Search

A saved search contains the collection of parameters that are used for a geocache query.  This can be used to quickly access geocaches that match the parameters specified in the saved search. Returns a single saved search by search_id or a list of saved searches.

Local Rules

Local Rules contains additional guidelines and restrictions for hiding caches in a specific location.

Photos

The photo API can be used to fetch images that have been added to a cache.

Write

HTTP POST requests are made to add new data or update existing data.  All requests require the user to be logged in.

Geocache

Create a new geocache or update an existing geocache.

Log

Create or update logs signifying a user found, attempted to find, or is leaving a note about a particular geocache.

Vote

Submit a vote for a geocache that is currently in review and update a votes that have already been submitted.

Series

Create, update and delete Series through this API call. 

Saved Search

Create, update and delete Saved Searches through this API call.

Photos

Add and remove photos as well as update photo meta-data with this API call.