Submit a log entry

:: services/logs/submit method

Code of the geocache.

Type of the log entry. This may be one of:

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

• Ready to search, Temporarily unavailable or Archived for caches owned by your user. This will set the corresponding geocache status.

  Note that Ready to search is inconsistently named; the corresponding geocache status is Available.

Depending on the geocache and user status, there can be additional restrictions on what log types are currently available. If those additional criteria are not met, OKAPI returns success=false and an explanatory message. The submittable_logtypes field of services/logs/capabilities tells which types are available.

Text to be submitted with the log entry.

Note: Some OCPL-based sites support only BMP (Basic Multilingual Plane) Unicode characters on some database fields. If you submit characters from outside of the BMP plane (known as "supplementary planes", they include characters such as smiley symbols), then keep in mind that your text might be saved garbled.

Default value: auto

Indicates the format of your comment. Three values allowed: auto, html or plaintext. You should NOT use the auto option, because its exact behavior is unspecified (more info). It is only included for backward compatibility.

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.

Default value: The current date and time

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!). You MAY (and are encouraged to) omit the time segment (and just submit a date in "yyyy-mm-dd" format) if the time is either unknown or your user doesn't want to disclose it.

Indicates when the cache was searched. 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. If only the date is given, OKAPI will publish the log in a way which most closely resembles "no time given" (more info).

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

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 success or error messages.

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.

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

Important: logtype has to be "Found it" or "Attended" in order to use this argument. The rating may be rejected if the user already rated this cache. You may consult the can_rate field of services/logs/capabilities to find out if the rating will be accepted.

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

Note: Some OKAPI installations do not support cache ratings. On such installations user's rating will always be ignored (if you include the rating, log entry will be posted successfully, but rating will be ignored). The has_ratings field of services/caches/capabilities tells if ratings are avaialble at this installation.

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). The can_recommend field of services/logs/capabilities tells if those criteria are currently met.

Default value: null

Valid options include:

• null - indicates that the user doesn't want to include any report on the current condition of the geocache.

• true - use this to indicate that your user thinks that the cache needs some special attention of its owner. Such users should also describe why it needs 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 set this option to true (one of them with empty comment).

• OCDE false - use this to indicate that your user thinks that the cache's condition is fine.

  Note: The false option currently is not evaluated by some installations. They will just ignore it.

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

You may query the can_set_needs_maintenance and can_reset_needs_maintenance fields of services/logs/capabilities to find out if all preconditions are met for submitting true or false, i.e. if it will succeed or be ignored.