Search your media

GET

/search

const url = 'https://api.colourbox.com/search?media_count=500&media_offset=0&media_type=image%2Bvideo&orientation=horizontal&thumbnail_size=110px&order=relevance&direction=asc&resolution=a3&query_type=strict_and_search&exclude_expired_media=false';
const options = {method: 'GET', headers: {Authorization: 'CBX-SIMPLE-TOKEN Token=<token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.colourbox.com/search?media_count=500&media_offset=0&media_type=image%2Bvideo&orientation=horizontal&thumbnail_size=110px&order=relevance&direction=asc&resolution=a3&query_type=strict_and_search&exclude_expired_media=false' \
  --header 'Authorization: CBX-SIMPLE-TOKEN Token=<token>'

At least one of q, unique_media_id or folder_ids MUST be applied to a search in order to get back a search result.

Return Values

When searching you need to specify which values you need in the result. You need to specify at least one value. The list to choose from is:

keywords	Keywords on media
media_type	The media type. Possible values are “image”, “vector”, “video” or “generic”. “generic” covers all file types that Colourbox do not process, e.g. Word documents and the like
height	Height in pixels
width	Width in pixels
unique_media_id	The ID for specific media
folder_id	The folder the media resides in
created	The date the media was imported into colourbox.com
title	The title of the media if any
description	The description of the media if any description
thumbnail_url	Publicly accessible URL of the thumbnail. NOTE that the URL is short-lived, 24 hours, signed and not persistent. Do not store these URLs indefinitely. If you desire to cache the result, you should probably cache it for 23 hours at maximum.
thumbnail_url_ssl	Publicly accessible HTTPS URL of the thumbnail. NOTE that the URL is short-lived, 24 hours, signed and not persistent. Do not store these URLs indefinitely. If you desire to cache the result, you should probably cache it for 23 hours at maximum.
filename	The original filename
copyright	Copyright information for the media
camera_created	The date the media was shot if the information was available in metadata when the media was uploaded
byline	The photographer/creator of the media
file_mimetype	The mime type of the media
file_disksize	The size of the media in bytes (this is the size of the file when it was uploaded; the download size typically differs from this since we attempt to patch metadata from our system into the file whether it has been changed since uploading it or not)
uploaded_by	The user ID of the user who uploaded the media
geo_location	The location the image was taken, if available. If the location is available you get `{latitude, longitude}`, else `{}`

Search Algorithm

The q parameter in a search can consist of several terms. A term being a sequence of letters and numbers separated from other terms by a +. Each term is matched against a subset of the fields on the files. The Skyfish API will try and match the query on the following fields on files:

keywords
title
description
copyright
uploaded_by
filename

It is also possible to exclude a term in the query string. This is done by prefixing the term with a -. There should no space between the hyphen and the term.

Please note that the actual algorithm for doing the search is subject to ongoing changes.

Search Data Normalization

All search data are put in unicode normalization form C (NFC), before added to our search engines. We do this to ensure that searching works efficiently, smoothly and seamlessly when searching with non-latin letters and special characters. All input queries are automatically put in unicode normalization for c as well.

Thumbnails

Skyfish automatically generates thumbnails in all relevant sizes for uploaded images. If you have uploaded non-image media via Skyfish, then generic thumbnails are returned for all extensions known to Skyfish.

Note that generic thumbnails have the same size, no matter what size you have requested. Generic thumbnails have size 93x119 pixels.

Authorizations

simple_token

Parameters

Query Parameters

string

The query string that you want to search for, e.g. “cat”. See Search Algorithm for details on which fields are matched.

return_values

string

Specifies which values you want back. The list should be a string with + as separator, e.g. unique_media_id+keywords. See Return Values for a complete list.

media_count

integer

default: 500 >= 1

Limits the number of results. Assumed default if omitted.

media_offset

integer

How many rows should be skipped from the start of the result. Mainly used for pagination.

media_type

string

Example

image+video

Specifies the type of media you are searching for, and the value must be one of the following: “image”, “vector”, “video” and “generic”. If not set, we include media from all types. You can specify multiple by separating them with a “+”.

folder_ids

string

Limits the folders in which the search is performed. Multiple folder IDs should be concatenated with “+”

unique_media_id

string

Limits the search to only being done on the given unique medias. Multiple unique media IDs should be concatenated with “+”

date_filter_field

string

If you want to filter by dates, you specify either created or camera_created. Created is the point in time when we got a hold of the image. Camera created is the point in time when the picture was taken, given the camera wrote the camera created exif tag.

min_date

string

Specifies the min. date for the date filter field. 2016-03-14T12:23:51Z. This is greater than or equal.

max_date

string

Specifies the max date for the date filter field. This is less than or equal.

orientation

string

Allowed values: horizontal vertical

Limits search to media of specified orientation

thumbnail_size

string

default: 320px

Allowed values: 110px 200px 320px 480px 800px 1200px 1600px

Returned thumbnail URLs in the selected size, if thumbnail_url or thumbnail_url_ssl is given in return_values.

order

string

Allowed values: relevance created

Order the search result. Created is the time the media was imported into the Colourbox system.

direction

string

Allowed values: asc desc

Specify the direction of the ordering. Note that this option can only be given if order is given as well.

resolution

string

Allowed values: a3 a4

This will restrict the search result to images which has resolution at least a4 or a3.

min_width

integer

Specifies the minimum width.

min_height

integer

Specifies the minimum height.

query_type

string

Allowed values: strict_and_search wildcards

Specifies the query type.

strict_and_search - Search result which only matches whole words
wildcards - Result which bends over backwards to provide as many results as possible

exclude_expired_media

boolean

Specifies if expired media should be excluded from the search

min_expiration_date

string

yyyy-mm-dd, Specifies to only include media with expiration date grater or equal to the date specified.

max_expiration_date

string

yyyy-mm-dd Specifies to only include media with expiration date less or equal to the date specified.

Responses

200

Example response from /search?q=cat&return_values=title+keywords&media_count=1

application/json

object

response

object

hits

integer

media

Array<object>

object

Example

{
  "response": {
    "hits": 34497,
    "media": [
      {
        "keywords": [
          "cat ",
          "cute ",
          "purebred ",
          "animal ",
          "attentive ",
          "beautiful ",
          "bow ",
          "domestic ",
          "feline ",
          "fur ",
          "furry ",
          "gaze ",
          "head ",
          "look ",
          "mammal ",
          "nose ",
          "pedigree ",
          "pedigreed ",
          "pet ",
          "portrait ",
          "pretty ",
          "shorthair ",
          "sideburns ",
          "stare ",
          "sweet ",
          "watchful ",
          "watching ",
          "whiskers ",
          "white background "
        ],
        "title": "Cat with blue eyes over white background"
      }
    ]
  }
}