rev. 1076

Submit a log entry
:: services/logs/submit method

Minimum Authentication: Level 3 (see Authentication Levels)

Submit a log entry for the geocache. Please note, that you won't be able to use this method until you learn to handle OAuth.

cache_code required

Code of the geocache.

logtype required

Type of an entry. This should be one of:

  • Will attend, Attended or Comment for Event caches;
  • Found it, Didn't find it or Comment for all other cache types.
comment optional

Text to be submitted with the log entry.

comment_format optional

Default value: auto

Indicates the format of your comment. Three values allowed: auto, html or plaintext. Usually, you should not use the auto option, because its exact behavior is unspecified and may depend on the installation (more info).

Important note: Unfortunatelly, some OC nodes don't support this parameter properly - regardless of what you choose, you may end up with unexpected results. Currently, there is nothing OKAPI developers can do to fix this, but you should use this parameter either way (to indicate how you expect it to behave) - we hope this will be fixed, eventually.

Important note: The subset of allowed HTML elements is left undefined and may change in the future. For future-compatibility, you should use only basic formatting tags.

when optional

A date and time string. This should be in ISO 8601 format (currently any format acceptable by PHP's strtotime function also will do, but most of them don't handle time zones properly, try to use ISO 8601!).

Indicates when the cache was found. If given, the log will be published with the given date and time. If not, log will be published using the current date and time.

password optional

Some caches require a password in order to submit a "Found it" log entry. You may check if this cache requires password with req_passwd field of the services/caches/geocache method.

langpref optional

Default value: en

Pipe-separated list of ISO 639-1 language codes. This indicates the order of preference in which language will be chosen for error messages.

on_duplicate optional

Default value: silent_success

How should OKAPI react when you are trying to submit a duplicate entry? One of the following values:

  • silent_success - try to respond with success=true, but don't add a new log entry (existing log_uuid will be returned),
  • user_error - respond with success=false and a proper user message,
  • continue - don't detect duplicates (note, that this will still fail in some cases, i.e. when you're trying to submit a "Found it" entry for an already found cache).

Note, that duplicate detection may take the when parameter into account. When you don't supply it, "when" is generated for you. This means that you may have to supply the "when" parameter if you want duplicate detection to work.

rating optional

An integer in range between 1 and 5 - user's optional rating of a found cache.

Important: logtype has to be "Found it" in order to use this argument.

Note: You should allow your user to not rate a found cache.

Note: Currently, some OC installations do not support cache ratings. On such installations user's rating will be ignored (if you include the rating, log entry will be posted successfully, but rating will be ignored).

recommend optional

Default value: false

Set to true if the user wants to recommend this cache.

Important: logtype has to be "Found it" or "Attended" in order to use this argument. However, some installations do not support recommending event caches (if you include a recommendation, the log entry will be posted successfully, but the recommendation will be ignored).

Recommending may only succeed when the user meets certain criteria set on him by the OC site. If criteria are not met, the request will end with user error (HTTP 200, success=false).

needs_maintenance optional

Default value: false

Set to true if the user thinks that the cache needs some special attension of its owner. Users should describe the reason for maintenance in their comments.

Note: Depending on OC installation and user's log entry type, OKAPI may actually publish two separate log entries when you check this flag (one of them with empty comment). Even then, you will still receive only one UUID reference (pointing to only one of those entries). Moreover, on some OC servers this flag might be completely ignored (not all OC servers support this feature).

Note: Currently, this is not allowed for Event Caches (you will get a HTTP 200 "user friendly" response).

format optional Standard common formatting argument.
callback optional Standard common formatting argument.
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

A dictionary of the following structure:

  • success - true, if the log entry was submitted successfully,
  • message - plain-text string, a message for the user, which acknowledges success or describes an error (usually you want to display this only when success is false),
  • log_uuid - ID of the newly created log entry, or null in case of an error.