Geocaching.su API

Introduction

OAuth 1

Please use following adresses and key/secret obtain from administrators to authenticate users:
TypeAddress
Request/api/oauth/request_token.php
Authorize/api/oauth/authorize.php
Access /api/oauth/access_token.php
There are two ways to work with the API. First is when you want to get access for user's data from your website. In this case you may redirect your user to https://geocaching.su/api/oauth/logon.php for entering his credentials and work with callback afterwards.
Second is to use it from the code directly, when user has provided his\her credentials into your application. In order to perform an OAuth dance following steps are required
Attention: unless opposite specified, all requests mean to be full OAuth-signed requests like
    GET /api/oauth/access_token.php?
        oauth_consumer_key=1236b9050c8e51cbe704865ba8ba110d05770ff51&
        oauth_nonce=106d1f871943cd5aab89dab651542535&
        oauth_signature_method=HMAC-SHA1&
        oauth_timestamp=1534950899&
        oauth_token=82984b5060a298a2bd14201de9d329b205b7d7df3&
        oauth_version=1.0&
        oauth_signature=0L8aja9Lf1fSPAOOBalpZmziZbU%3D
    

Attention 2: parameters have to be sorted alphabetically, in other case signature verification will fail.:
    GET /api/geocache.php?
        id=2197&         <----- This should go before oauth parameters
        oauth_consumer_key=1236b9050c8e51cbe704865ba8ba110d05770ff51&
        oauth_nonce=aa772ec03d0acdb737865030138ae7db&
        oauth_signature_method=HMAC-SHA1&
        oauth_timestamp=1534950899&
        oauth_token=a2108f724e0eea692913c5b6c0f7682505b7d7df3&
        oauth_version=1.0&
        oauth_signature=iDr1Ku45s8%2F%2BATY%2FWGwUbaw6YKI%3D
    

Reply format and errors

API replies to all requests with dictionary containing two keys - "status" - which indicates request processing status and "data" which contains response data (if any), i.e.:
{"status":{"code":"OK"},"data":[]}
			
"Status" dictionary comes with "code" key which may have "OK" or "ERROR" value (string). If request processing ended with errors, "status" dictionary will contain additional information about it:
{"status":{"code":"ERROR","type":"AuthorisationRequired","description":"Request wasn't signed"},"data":[]}
There are 3 error types:
WrongParameters
Not all parameters are set, or parameters submitted in wrong format
AuthorisationRequired
Authorisation error. This status returned when any authorisation error is occured. I.e. request was not signed, request was signed with expired token, etc

Important notice:You should be ready to handle this type of error in any time. Although there's virtually no TTL for obtained OAuth tokens, they may be expired or invalidated by server. Best practice is try to re-authenticate user when you receive this kind of error for the first time.
SeeDescription
This status returned when some unexpected, abnormal situation has occured.

It's highly discouraged to use string passed in "description" key somewhere in yours app logic flow. Please treat it as hint for developer.

Supported requests

List of geocaches in rectangular area

URL: /api/list.php
Type: GET

This request requires 4 parameters (minlat, maxlat, minlng, maxlng) in floating point number format, which defines bounding box of requested area.
In reply, list of geocaches in this are will be returned. It will contain only brief data, as shown below.

Example:
/api/list.php?minlat=A&maxlat=B&minlng=C&maxlng=D
Reply:
{
	"status":{"code":"OK"},
	"data":[
		{
			"id":(geocache ID, int),
			"name":(geocache name, string),
			"author":{
				"id":(geocache author id, int),
				"name":(geocache author name, string)
			},
			"latitude":0.0,
			"longitude":0.0,
			"type":(geocache type, int, see in Geocache section),
			"typeString":(geocache type, int, see in Geocache section),
			"attributes":(array of geocache attributes),
			"status":(geocache status, int),
			"statusString":(geocache status, string),
			"difficulty":1,
			"area":1,
			"isFound":(is found by current user, boolean),
			"dateHidden":"2000-01-01"
		}
	]
	// other geocaches, if any
}
			

List of geocaches around the given point

URL: /api/list_center.php
Type: GET

Returns list of caches in area defined by center and radius.
Center (lat, lng) - float coordinates of the center point.
Radius (radius) - float radius, in km.
Reply is the same as from list.php

Full data of geocache

URL: /api/geocache.php
Type: GET

This method accepts only one parameter - 'id' which should be passed via GET request and should have int format.

If geocache with specified id is not found, error will be returned, i.e.:
{"status":{"code":"ERROR","type":"WrongParameters","description":"Specified geocache was not found."},"data":[]}
			
Otherwise, full information about specified geocache is returned:
{
	"status":{"code":"OK"},
	"data":{
		"id":(geocache id, int),
		"name":(geocache name, string),
		"author":{
			"id":(author user id, int),
			"name":(author name, string)
			},
		"latitude":0.0,
		"longitude":0.0,
		"type":1,
		"typeString":"Traditional",
		"attributes":[{
			"id":(attribute id, int),
			"name":(attribute name, string)
			}, //...other attributes, if any
		],
		"status":1,
		"statusString":"Active",
		"difficulty":3,
		"area":4,
		"isFound":(is found by current user, boolean),
		"winter":(seasonal availability, see "Winter Mode" chapter below),
		"dateHidden":"2016-05-20",
		"description":{
			"container":(description of geocache container and/or contents. string),
			"cache":(geocache description, string),
			"area":(area description, string),
			"traditionalPart":(traditional part, string, see Winter Mode chapter below),
			"virtualPart":(virtual part, string, see Winter Mode chapter below),
			"isHtml":(should descriptions be treated as html-formatted text, boolean)
		},
		"logs":[{
			"id":(logbook note id, int),
			"typeString":(type of logbook record, string, see Adding records to geocache logbook for details),
			"author":{
				"id":(id of note author, int),
				"name":(name of note author, string)
				},
			"date":(datetime when this note was added, string, in format "0000-00-00 00:00:00"),
			"text":(text, string)
			}, //....other notes, if any
			],
		"images":[{
				"id":(image id, int),
				"type":(image type, "areaPhoto" or cachePhoto),
				"url":(image url, string),
				"description":(photo description, string, may not be presented)
			}]
	}
}
			

Winter mode

Value of 'winter' key in full geocache information dictionary may have following values:

ValueMeaning
availableWinter mode is off, user may find geocache as usual.
virtualWinter mode is on, user should find answer to virtual question (virtualPart key) instead of trying to find geocache's container.
unavailWinter mode is on, geocache is not available.
Important notice: if 'winter' key is not present in full geocache information dictionary, it should be assumed as 'available'.

Although you application may behave like a geocaching.su web site and not show traditionalPart description while winter mode is on, it may actually be good practice to show all available information about geocache with additional notice about active winter mode instead. Especially, if you application stores data locally, as winter mode may be turned on or off by author in any time.

Adding records to geocache logbook

URL: /api/note.php
Type: POST

Following parameters are accepted via POST method:
cacheID (int)ID of geocache for which note is submitted
type (string)Type of note, one of following value:
foundUser found a geocache
notFoundUser wasn't found a geocache
commentJust comment for geocache
visitedNotTriedToFindUser visited place near geocache, but wasn't tried to find it
text (string)Text of published note. User's experience about finding geocache should be shared here. Please do not use auto-generated text here. If text provided here is very short - note will be rejected.

If logbook entry was successfully added, ID assigned for it will be returned, otherwise error will be reported.

Example:
{"status":{"code":"OK"},"data":{"noteID":123456}} 
			

Marking caches as watched

URL: /api/mark.php
Type: POST

Following parameters are accepted via POST method:
cacheID (int) ID of geocache which is affected
watched (bool) "true", if it's needed to mark the cache as watched, "false" if it's needed to "unwatch' the cache

Uploading photo to album

URL: /api/photo.php
Type: POST

Following parameters are accepted via POST method:
cacheID (int)ID of geocache where to upload photo
image (string)Base64-encoded image
caption (string)(Optional) Title of the photo

If the photo was successfully added, "success: true" will be reported and URL of the image will be returned, otherwise error will be reported.

Example:
{"status":{"code":"OK"},"data":{"success":"true", "image_url": "https://geocaching.su/photos/albums/343333.jpg"}}
			

Adding personal notes

URL: /api/personal_note.php
Type: POST

Updates user's personal note for the given cache. Following parameters are accepted via POST method:
cacheID (int) ID of geocache where to update note photo
note_test (string) Text of the note. Shouldn't be more than 10k chars

User profile

URL: /api/profile.php
Type: GET

Gets User profile. There are three possible ways to call this method: Error will be returned if both userID and profileID are passed.

Example:
{
	"status":{"code":"OK"},
	"data":{
		"id":(user id, int),
		"profileID":(user profile id, int),
		"name":(user name, string),
		"foundCaches":(amount of geocaches found by user, int),
		"hiddenCaches":(amount of geocaches hidden by user, int)
	}
}