Getting Started

The API allows you to query all the data stored in the 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 API you need a developer key. 

Terms of Use

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


General ideas behind how and the API work.

Creative Commons

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

REST Web Service Interface

The 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.


User authentication and authorization to 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.


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


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.


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


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


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


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.


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


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


Create a new geocache or update an existing geocache.


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


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


Create, update and delete Series through this API call. 

Saved Search

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


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