Skip to content

Search API Endpoints

GET /api/v1/photos

When querying the /api/v1/photos endpoint, matching files will be returned along with the metadata of the corresponding photos. This may be unexpected at first due to the endpoint name. However, this approach allows to sort results e.g. by color or file size, which differ at the file level and therefore require dynamic sorting/grouping of multiple matching files that may belong to the same photo (see Stacks).

To simplify processing in the client/user interface, you can set the merged parameter to true so that consecutive files with the same photo ID are merged into a single result with the Files property containing the related files.

In particular, multiple files are returned for a single photo in the case of multi-file/hybrid media formats such as Live Photos, as these consist of a photo and a video file. The same applies to RAW/JPEG.

If you only want the primary image (thumbnail) to be returned, you can set the primary filter to true. In this case, it is not necessary to also set merged to true as a single file will be returned for each photo. This can simplify things if you don't need to know anything about the additional files, e.g. when just rendering thumbnails without metadata.

Composite ID and UIDs

The ID returned by the search API is a composite ID consisting of the photo ID and the related file ID (usually the file selected as primary image), so that this ID is unique as required for rendering in the user interface.

Note that you do not need this composite ID to communicate with any of our API endpoints. Instead, you will either have to pass a UID (e.g. when updating photo metadata) or the SHA1 Hash of a file (e.g. when requesting a thumbnail).

Using random UIDs prevents possible caching issues in proxies/clients, e.g. if the index is reset on the server and the numeric IDs would thus start at 0 again. They are also hard to guess, so a time-consuming brute force attack is required instead of simply enumerating integers starting from 0.

Response Example

    "ID": "11-21",
    "UID": "pse1yzastu36irsj",
    "Type": "image",
    "TypeSrc": "",
    "TakenAt": "2012-08-27T12:40:25Z",
    "TakenAtLocal": "2012-08-27T14:40:25Z",
    "TakenSrc": "meta",
    "TimeZone": "Europe/Madrid",
    "Path": "2012",
    "Name": "20120827-144025-Bodegas-Ysios-Winery-Laguardia-Spain",
    "OriginalName": "",
    "Title": "Bodegas Ysios Winery / Laguardia / Spain",
    "Description": "",
    "Year": 2012,
    "Month": 8,
    "Day": 27,
    "Country": "es",
    "Stack": 0,
    "Favorite": false,
    "Private": false,
    "Iso": 100,
    "FocalLength": 28,
    "FNumber": 11,
    "Exposure": "1/160",
    "Quality": 4,
    "Resolution": 8,
    "Color": 2,
    "Scan": false,
    "Panorama": false,
    "CameraID": 5,
    "CameraSrc": "meta",
    "CameraSerial": "1730906408",
    "CameraMake": "Canon",
    "CameraModel": "EOS 30D",
    "LensID": 5,
    "LensModel": "EF28mm f/1.8 USM",
    "Lat": 42.568302,
    "Lng": -2.5908582,
    "CellID": "s2:0d4ff9b1b32c",
    "PlaceID": "es:7v314KSnaCLy",
    "PlaceSrc": "meta",
    "PlaceLabel": "Laguardia, Euskadi, Spain",
    "PlaceCity": "Laguardia",
    "PlaceState": "Euskadi",
    "PlaceCountry": "es",
    "InstanceID": "",
    "FileUID": "fse1yza2r4gsjq6f",
    "FileRoot": "/",
    "FileName": "2012/20120827-144025-Bodegas-Ysios-Winery-Laguardia-Spain.jpg",
    "Hash": "4bc82c3ea5aaa323aea801fe0125b554af8e49af",
    "Width": 3368,
    "Height": 2246,
    "Portrait": false,
    "Merged": false,
    "CreatedAt": "2024-05-25T17:52:22.291451832Z",
    "UpdatedAt": "2024-05-25T17:52:22.307889576Z",
    "EditedAt": "0001-01-01T00:00:00Z",
    "CheckedAt": "2024-05-26T06:15:09Z",
    "Files": [
        "UID": "fse1yza2r4gsjq6f",
        "PhotoUID": "pse1yzastu36irsj",
        "Name": "2012/20120827-144025-Bodegas-Ysios-Winery-Laguardia-Spain.jpg",
        "Root": "/",
        "Hash": "4bc82c3ea5aaa323aea801fe0125b554af8e49af",
        "Size": 2473990,
        "Primary": true,
        "Codec": "jpeg",
        "FileType": "jpg",
        "MediaType": "image",
        "Mime": "image/jpeg",
        "Width": 3368,
        "Height": 2246,
        "Orientation": 1,
        "AspectRatio": 1.5,
        "Colors": "616121222",
        "Luminance": "AACA5A888",
        "Diff": 767,
        "Chroma": 15,
        "CreatedAt": "2024-05-25T17:52:22.291451832Z",
        "UpdatedAt": "2024-05-25T17:52:22.307889576Z",
        "Markers": []

Response Headers

Header Type Example Notes
X-Count int 120 Actual number of files returned
X-Limit int 120 Maximum number of files requested
X-Offset int 0 File offset
X-Download-Token string 3qjg1db2 Security token required to download original files
X-Preview-Token string 174utza5 Security token required for the Thumbnail Image API

In order to fetch all results, you can perform a follow-up query if the number in the X-Count response header matches X-Limit. For this, the offset request parameter must be set to the number of files already returned.

Request Parameters

Name Type Example Notes
q string dog color:red Search query as entered by the user in the search toolbar, see Search Filters
s string ariqwb43p5dh9h13 Limits the result scope to the specified album UID
count int 1000 Maximum number of files to be returned
offset int 0 File offset
order string added Sort order e.g. added, updated, edited, relevance, duration, size, newest, oldest, similar, name, title, or random
merged bool true Merges consecutive files that belong to the same photo into a single result, see above for an explanation

Search Filters

The following search filters can be used as regular GET request parameters or submitted as part of a search query with the q request parameter:

Filter Type Examples Notes
dist decimal dist:50 Distance to Position (km)
lat decimal lat:41.894043 GPS Position (Latitude)
lng decimal lng:-87.62448 GPS Position (Longitude)
chroma number chroma:70 Chroma (0-100)
diff number diff:-1 diff:2 Differential Perceptual Hash (000000-FFFFFF)
quality number quality:0 quality:3 Minimum quality score (1-7)
album string album:berlin Album UID or Name, supports * wildcards
albums string albums:"South Africa & Birds" Album Names (combinable with & and |)
alt string alt:300-500 GPS Altitude (m)
camera string camera:canon Camera Make/Model Name
category string category:airport Location Category
city string city:"Berlin" Location City (separate with |)
color string color:"red|blue" Color Name (purple, magenta, pink, red, orange, gold, yellow, lime, green, teal, cyan, blue, brown, white, grey, black) (separate with |)
country string country:"de|us" Location Country Code (separate with |)
day string day:3|13 Day of Month (1-31, separate with |)
f string f:2.8-4.5 Aperture (f-number)
face string face:PN6QO5INYTUSAATOFL43LL2ABAV5ACZG Face ID, yes, no, new, or kind
faces string faces:yes faces:3 Minimum number of Faces (yes = 1)
favorite string favorite:true favorite:false Finds images by favorite status
filename string filename:"2021/07/12345.jpg" File Name with path and extension (separate with |)
folder string folder:"*/2020" Path Name (separate with |), supports * wildcards
geo string geo:yes Finds pictures with or without coordinates
hash string hash:2fd4e1c67a2d SHA1 File Hash (separate with |)
id string id:123e4567-e89b-... Finds pictures by Exif UID, XMP Document ID or Instance ID
iso string iso:200-400 ISO Number (light sensitivity)
keywords string keywords:"sand&water" Keywords (combinable with & and |)
label string label:cat|dog Label Names (separate with |)
latlng string latlng:"name" GPS Bounding Box (Lat N, Lng E, Lat S, Lng W)
lens string lens:ef24 Lens Make/Model Name
mm string mm:28-35 Focal Length (35mm equivalent)
month string month:7|10 Month (1-12, separate with |)
mp string mp:3-6 Resolution in Megapixels (MP)
name string name:"IMG_9831-112*" File Name without path and extension (separate with |)
near string near:pqbcf5j446s0futy Finds nearby pictures (UID)
olc string olc:8FWCHX7W+ OLC Position (Open Location Code)
original string original:"IMG_9831-112*" Original file name of imported files (separate with |)
path string path:2020/Holiday Path Name (separate with |), supports * wildcards
people string people:"Jane & John" Subject Names (combinable with & and |)
person string person:"Jane Doe & John Doe" Subject Names, exact matches (combinable with & and |)
s2 string s2:4799e370ca54c8b9 S2 Position (Cell ID)
scan string scan:true scan:false Finds scanned photos and documents
state string state:"Baden-Württemberg" Location State (separate with |)
subject string subject:"Jane Doe & John Doe" Alias for person
subjects string subjects:"Jane & John" Alias for people
title string title:"Lake*" Title (separate with |)
type string type:raw Media Type (image, video, raw, live, animated); separate with |
uid string uid:pqbcf5j446s0futy Limits results to the specified internal unique IDs
year string year:1990|2003 Year (separate with |)
animated switch animated:yes Finds animated GIFs
archived switch archived:yes Finds archived pictures
error switch error:yes Finds pictures with errors
hidden switch hidden:yes Finds hidden pictures (broken or unsupported)
landscape switch landscape:yes Finds pictures in landscape format
live switch live:yes Finds Live Photos and short videos
mono switch mono:yes Finds pictures with few or no colors
panorama switch panorama:yes Finds pictures with an aspect ratio > 1.9:1
photo switch photo:yes Finds only photos, no videos
portrait switch portrait:yes Finds pictures in portrait format
primary switch primary:yes Finds primary JPEG files only
private switch private:yes Finds private pictures
public switch public:yes Excludes private pictures
raw switch raw:yes Finds pictures with RAW image file
review switch review:yes Finds pictures in review
square switch square:yes Finds images with an aspect ratio of 1:1
stack switch stack:yes Finds pictures with more than one media file
stackable switch stackable:yes Finds pictures that can be stacked with additional media files
unsorted switch unsorted:yes Finds pictures not in an album
unstacked switch unstacked:yes Finds pictures with a file that has been removed from a stack
vector switch vector:yes Finds vector graphics only
video switch video:yes Finds video files only
added timestamp added:"2006-01-02T15:04:05Z" Finds pictures added at or after this time
after timestamp after:"2022-01-30" Finds pictures taken on or after this date
before timestamp before:"2022-01-30" Finds pictures taken on or before this date
edited timestamp edited:"2006-01-02T15:04:05Z" Finds pictures edited at or after this time
taken timestamp taken:"2022-01-30" Finds pictures taken on the specified date
updated timestamp updated:"2006-01-02T15:04:05Z" Finds pictures updated at or after this time