User Metadata

rokka can accept user defined metadata for each image and let's you search for them

Table of Contents


Image metadata is metadata added to a source image by the API user that does not change the image identifying hash. You can later also search for them, see the filtering for particular images chapter.

Image metadata types

Image metadata can be a string, integer, double, date, latitude/longitude or an array and also be changed after an image was uploaded.

The default type is String, if you want to store it as any other type, you have to specify it with a prefix. Refer to the following table for a prefix/type documentation:

Type Prefix
String str:
Text text:
Int int:
Double double:
Date date:
Location latlon:
Array with strings array:
Array with text array_text:

The difference between String and Text is that String fields are not tokenized and decompounded, it's stored as a literal string, you can only search the whole string or from the beginning with prefix searches. Text fields on the other hand are tokenized, decompounded and stemmed, so that you can search for all the words in that field.

Some limitations apply to each type, in particular:

  • the Date type accepts values with the following format:YYYY-MM-DDThh:mm:ssZ;
  • the Location type needs to be set as a latitude, longitude pair, eg: "47.38,8.52".
  • the elements of an Array type will always be stored as string, you can't specify a type there.

Add image metadata to a source image

Image metadata field names have a maximum length of 54 characters, and can be composed only of the following characters:

  • a-z (lower-case letters);
  • 0-9 (numbers);
  • _ (underscore).

The most flexible way to add/replace/delete fields is with a PATCH request and having the field data JSON-encoded in the body. This also allows to update more than one field at once.

curl -H 'Content-Type: application/json' -X PATCH '' -d '{
    "some_field": "some value",
    "str:some_string_field": "some value again",
    "int:some_umber": 0,
    "date:some_date": "2017-01-29T12:34:56Z",
    "array:some_array": ["Foo","Bar","Baz"],
    "delete_this": null

If you do a PUT instead of a PATCH request, then all existing fields will be deleted first.

If you want to update/add just one value, you can also do this by making a PUT request to{organization}/{hash}/meta/user/{name} and include the JSON encoded value in the body:

curl -H 'Content-Type: application/json' -X PUT '' -d '"somevalue"'

You can also directly provide metadata when you first upload an image. See Source images for details.

Delete metadata from a source image

Besides just setting a value of a field to null as shown above, you can also delete user metadata using a DELETE API call.

For a single field:

curl -H 'Content-Type: application/json' -X DELETE ''

Deleting all image metadata of an image:

curl -H 'Content-Type: application/json' -X DELETE ''