ver. 1958 (4e4db56)
services/apiref
services/apisrv
services/attrs
services/caches
services/caches/formatters
services/caches/map
services/caches/search
services/caches/shortcuts
services/logs
services/logs/images
services/oauth
services/replicate
services/users

The OKAPI Project
:: Opencaching API Reference

OKAPI is a publically available API for "National Opencaching" sites.

  • It provides OC site with a set of useful well-documented API methods,
  • Allows external developers to easily read public Opencaching data,
  • Allows read and write private (user-related) data with OAuth Authentication.

The project has grown to become a standard and common API for all National Opencaching.xx sites. This OKAPI installation provides services for the https://www.opencaching.us/ site. Here is the list of other OKAPI installations:

Other links you might want to check out:

* Opencaching.DE includes other sites - Opencaching.IT and Opencaching.FR - which are in fact the one site visible on multiple domains. All three share one database, so you can access all their data through Opencaching.DE OKAPI installation.

How can I use OKAPI?

We assume that you're a software developer and you know the basics.

OKAPI is a set of simple web services. Basicly, you make a proper HTTP request, and you receive a JSON-formatted response, that you may parse and use within your application.

Example. Click the following link to run a method that prints out the list of all available methods:

You've just made your first OKAPI request! This method was a simple one though. It didn't require any arguments and it didn't require you to use a Consumer Key. Other methods are more complex and require you to use your own API key.

Authentication Levels

Each OKAPI method has a minimum authentication level.

"Minimum" means that if you want to call a method which requires "Level 1" authentication, you have to use "Level 1" authentication or higher ("Level 2" or "Level 3" will also work).

Most methods can be called with "Level 1" authentication, so for most applications you won't have learn OAuth.

  • Level 0. Anonymous. You may call such methods with no extra authentication-related arguments.

    some_method?arg=44

  • Level 1. Simple Consumer Authentication. You must call this method with consumer_key argument and provide the key which has been generated for your application on the Sign up page.

    some_method?arg=44&consumer_key=a7Lkeqf8CjNQTL522dH8

  • Level 2. OAuth Consumer Signature. You must call this method with proper OAuth Consumer signature (based on your Consumer Secret). For most languages there are some OAuth 1.0a libraries which can do this for you.

    some_method
    ?arg=44
    &oauth_consumer_key=a7Lkeqf8CjNQTL522dH8
    &oauth_nonce=1987981
    &oauth_signature_method=HMAC-SHA1
    &oauth_timestamp=1313882320
    &oauth_version=1.0
    &oauth_signature=mWEpK2e%2fm8QYZk1BMm%2fRR74B3Co%3d

  • Level 3. OAuth Consumer+Token Signature. You must call this method with proper OAuth Consumer+Token signature (based on both Consumer Secret and Token Secret). For most languages there are some OAuth 1.0a libraries which can do this for you.

    some_method
    ?arg=44
    &oauth_consumer_key=a7Lkeqf8CjNQTL522dH8
    &oauth_nonce=2993717
    &oauth_signature_method=HMAC-SHA1
    &oauth_timestamp=1313882596
    &oauth_token=AKQbwa28Afp1YvQAqSyK
    &oauth_version=1.0
    &oauth_signature=qbNiWkUS93fz6ADoNcjuJ7psB%2bQ%3d

GET or POST?

Whichever you want. OKAPI will treat GET and POST requests equally. You may also use the HTTP Authorization header for passing OAuth arguments. OKAPI does not support other HTTP request types (such as PUT or DELETE).

A warning about HTML fields

Many of the fields returned in OKAPI responses are formatted in HTML. However, most of these fields come directly from the underlying Opencaching database. Currently, these fields are not validated by OKAPI. They should be validated by the Opencaching site itself (prior to inserting it to the database), but we cannot guarantee that they will be. And you shouldn't count on it too.

You must assume that our HTML content may contain anything, including invalid HTML markup, tracking images (pixels), or even XSS vectors. This also applies to the descriptions included in the GPX files.

Common formatting parameters

Most of the methods return simple objects, such as lists and dictionaries of strings and integers. We may format such objects for you in several ways. If you want to change the default (JSON) then you should include common formatting parameters in your request:

  • format - name of the format in which you'd like your result to be returned in. Currently supported output formats include:

    • json - JSON format (default),

    • jsonp - JSONP format (if you choose this one then you have to specify the callback parameter too),
    • xmlmap - deprecated (why?),
    • xmlmap2 - XML format. This is produced by mapping JSON data types to XML elements.
  • callback - (when using JSONP output format) name of the JavaScript function to be executed with the result as its parameter.

Some methods expose formatting of their own, for example, they may return a JPEG or GPX file. Such methods do not accept common formatting parameters.

Important: Almost all of the returned data types are extendible. This means, that (in future) they may contain data that currently they don't. Such data will be included in backward-compatible manner, but still you should remember about it in some cases (i.e. when iterating over attributes of an object). This additional data may appear as extra elements in GPX files or extra keys in JSON responses. Your software must ignore such occurrences if it doesn't understand them!

OAuth Dance URLs

If you want to use Level 3 methods, you will first have to perform "the OAuth dance" (series of method calls and redirects which provide you with an Access Token).

The three OAuth request URLs defined in the OAuth specification are:

Things you should pay attention to:

  • The oauth_callback argument of the request_token method is required.

    As the OAuth 1.0a specification states, it should be set to "oob" or a callback URL (this usually starts with https://, but you can use any other scheme, e.g. myapp://).

    For most OAuth client libraries, you just should provide "https://www.opencaching.us/okapi/services/oauth/request_token?oauth_callback=oob" as the request_token URL, to get it started. Later on, you'll probably want to replace "oob" with something more useful (your own callback).

  • The oauth_verifier argument of the access_token method is also required.

    When user authorizes your application, he will receive a PIN code (OAuth verifier). You have to use this code to receive your Access Token.

  • Access Tokens do not expire (but can be revoked). This means, that once the user authorizes your application, you receive a "lifetime access" to his/her account. The user may still revoke access to his account from your application - when this happens, you will have to redo the authorization dance.

Advanced error handling

Basic rules apply:

  • If all goes well, OKAPI will respond with a HTTP 200 status.
  • If there is something wrong with your request, you will get a HTTP 4xx response. The body will contain a JSON object describing the error (see below). These kind of responses should trigger some kind of an exception inside your application.
  • If something goes wrong on our part, you will get a HTTP 5xx response. Usually you should treat such errors as other I/O errors (e.g. display a "No connection, try later" notice). We will try to fix such errors as soon as possible.
  • Sometimes, due to invalid server configuration, you may receive HTTP 200 instead of HTTP 500. We know that's "unprofessional", but we cannot guarantee that all OC servers are configured properly (example). If you get HTTP 200 and you cannot parse the server response, you should treat it as HTTP 500.

Every HTTP 4xx error will contain an additional description in the response body. This description will be always formatted in JSON (regardless of the format parameter you might have used in your request). You can use this information to pinpoint the source of the error.

The error response is a dictionary with a single error key. Its value contains at least the following keys:

  • developer_message - description of the error,
  • reason_stack - a list of keywords which depicts the exception's position in our exception class hierarchy (see below for valid values),
  • status - HTTP status code (the same which you'll get in response HTTP header),
  • more_info - url pointing to a more detailed description of the error (or, more probably, to the page you're now reading).

Depending on the values on the reason_stack, the error dictionary may contain additional keys. Currently possible values of the reason_stack include:

  • ["bad_request"] - you've made a bad request.

    Subclasses:

    • [ "bad_request", "missing_parameter"] - you didn't supply a required parameter. Extra keys:

      • parameter - the name of the missing parameter.
    • [ "bad_request", "invalid_parameter"] - one of your parameters has an invalid value. Extra keys:

      • parameter - the name of the parameter,
      • whats_wrong_about_it - a string, pretty self-explanatory,
  • ["invalid_oauth_request"] - you've tried to use OAuth, but your request was invalid.

    Subclasses:

    • [ "invalid_oauth_request", "unsupported_oauth_version"] - you have tried to use unsupported OAuth version (OKAPI requires OAuth 1.0a).

    • [ "invalid_oauth_request", "missing_parameter"] - you didn't supply a required parameter. Extra keys:

      • parameter - the name of the missing parameter.
    • [ "invalid_oauth_request", "unsupported_signature_method"] - you tried to use an unsupported OAuth signature method (OKAPI requires HMAC-SHA1).

    • [ "invalid_oauth_request", "invalid_consumer"] - your consumer does not exist.

    • [ "invalid_oauth_request", "invalid_token"] - your token does not exist. This error is pretty common! Your token may have expired (in case of request tokens) or may have been revoked (in case of access tokens). You should ask your user to redo the authorization dance.

    • [ "invalid_oauth_request", "invalid_signature"] - your request signature was invalid.

    • [ "invalid_oauth_request", "invalid_timestamp"] - you used a timestamp which was too far off, compared to the current server time. This error is pretty common, especially if your app is for mobile phones! You may ask your user to fix his clock, or you could use the provided extra keys to adjust your oauth_timestamp parameter yourself. Extra keys:

      • yours - UNIX timestamp you have supplied (this used to be a string, but now it is being casted to an integer, see here),
      • ours - UNIX timestamp on our server,
      • difference - the difference, in seconds (to be added to your clock),
      • threshold - the maximum allowed difference.
    • [ "invalid_oauth_request", "nonce_already_used"] - most probably, you have supplied the same request twice (user double-clicked something?). Or, you have some error in the nonce generator in your OAuth client.

In most cases, you should be fine with catching just the following (order significant):

  • ["invalid_oauth_request", "invalid_token"] (reauthorize),
  • ["invalid_oauth_request", "invalid_timestamp"] (adjust the timestamp),
  • any other 4xx status exception (send yourself a bug report).
  • All other errors - including HTTP 5xx responses, JSON parsing errors, timeouts etc. - should be treated as connection errors (ask the user to try later).

Important backward compatibility note: If Z is a subclass of X, then it will forever stay a subclass of X. However, class X won't necessarilly stay Z's direct parent. This means that ["x", "z"] may become ["x", "y", "z"] or even ["w", "x", "y", "z"] one day. In other words, instead writing if (reason_stack == ["x", "z"]) { ... } you should rather use if ("z" in reason_stack) { ... }.

Differences between Opencaching sites

Client developers should be aware that there are some differences between Opencaching sites. E.g. Opencaching.US currently does not support OKAPI log image upload, but is the only site that provides "podcast geocaches". OKAPI implements several mechanisms that either level those differences - you don't need to care about them - or allows your application to automatically adjust to the Opencaching site's capabilities.

OKAPI versions

Now and then, new features are added to OKAPI. They will be listed in the Changelog, including version numbers. Applications may compare those numbers to the installation's current OKAPI version number, as returned by the site's services/apisrv/installation method, to detect if a new feature is available.

Site capabilities

OKAPI methods generally are designed to abstract from differences between OC installations. E.g. if some geocache or log property is not implemented, OKAPI still allows to request it, but will return null or false (as explained in the method docs). When submitting data, unsupported options are mostly ignored (as documented), or OKAPI will return an HTTP 200 result with the success=false field and a user-friendly explanation (as documented).

However, when searching for caches or submitting content, there are some exceptions where developers may need to know about the site's capabilities. The docs then will refer to one of the following methods, that your application can call to find out what features are available:

These methods also return information that allows to hide nonfunctional options from user interfaces. E.g. you may want to disable searching for geocaches by rating, if OKAPI would ignore the user's input (because the OC site does not implement ratings).

Branch tags

Throughout the OKAPI documentation, you will encounter options and fields that are tagged as "OCPL" or "OCDE". These tags have the following meaning:

  • OCDE - This feature currently is only in use at Opencaching sites that are based on the OCDE software branch (currently Opencaching.DE/IT/FR). If your application is NOT intended to be used with those sites, you may want to skip this feature and not implement it.
  • OCPL - This feature currently is only in use at Opencaching sites that are based on the OCPL software branch (currently Opencaching.PL, NL, US, UK, RO). If your application is NOT intended to be used with those sites, you may want to skip this feature and not implement it.

In all other us cases, you are recommended to ignore the branch tags. See above for more information on differences between Opencaching sites.

If you have any questions about this, then ask them here.

How can I participate in OKAPI development?

OKAPI is Open Source and everyone is welcome to participate in the development.

We have our issue tracker. You can use it to contact us!
You may also contact some of the developers directly, if you want.

Visit project homepage for details: https://github.com/opencaching/okapi/

List of available methods

OKAPI web services (methods) currently available on this server: