ver. 1958 (4e4db56)

Add an image to a log entry
:: services/logs/images/add method

Minimum Authentication: Level 3 (see Authentication Levels)

Attach a new image to an existing log entry.

log_uuid required

ID of the log entry to which the image will be attached. The user of your Access Token must be the author of this log entry.

image required

Base64-encoded image file; must be in JPEG, PNG or GIF format.

There are some dynamic limits on the file size and dimensions of uploaded images; you should query them via the service/apiserv/installation method before uploading. The image may be shrunk, rotated, EXIF-stripped or otherwise be processed before it is stored.

caption optional

Plain-text string, a caption of the image. Captions are usually displayed along with the images.

You MAY allow your user to attempt submitting anything here (including an empty caption), but you should always be prepared to receive false in the success field due to restrictions on what captions are accepted.

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.

is_spoiler optional

Default value: false

Set this to true to indicate that the submitted image contains hints for finding the geocache, i.e. it shows the hiding place. Spoiler images usually will not be shown to users by default, but replaced by a clickable placeholder or caption that leads to the image.

position optional

Indicates the wanted position of this image on the log entry's list of images. By default, new images will be appended to the end of this list.

The value is 0-based (so, if you want this image to be displayed as the first one, you should use the 0 value). The position of the image which currently takes the given spot will be shifted downwards (you can never replace any image using this method). If you provide an invalid value (e.g. greater than the number of images), then OKAPI will try to use the its best guess (e.g. append the image to the end).

Note: Some installations will ignore this option and always append new images to the end of the list. The services/apisrv/installation method tells if image positioning is available.

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.

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 image 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),
  • image_uuid - ID of the appended image, or null in case of an error,
  • image_url - URL of the appended image, or null in case of an error,
  • position - 0-based position of the appended image on the log entry's list of images; null in case of an error.