ver. 1926 (dbed1d0) 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 |
Submit a log entry
|
|
||||
https://www.opencaching.de/okapi/services/logs/submit | ||||
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 the log entry. This may be one of:
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. |
||
comment | optional |
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. |
||
comment_format | optional |
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. |
||
when | optional |
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). |
||
password | optional |
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. |
||
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 success or 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:
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" 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. |
||
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). The can_recommend field of services/logs/capabilities tells if those criteria are currently met. |
||
needs_maintenance | optional |
Default value: false Deprecated (why?). Use needs_maintenance2 instead. Passing true here will have exactly the same meaning as passing true to needs_maintenance2. Passing false however has a different meaning - it's the same as passing null (not false!) to needs_maintenance2. Keep this in mind when upgrading your application to needs_maintenance2! |
||
needs_maintenance2 | optional |
Default value: null Valid options include:
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. |
||
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:
|