Package: amazon-photos
Amazon Photos APITable of ContentsInstallationSetupExamplesSearchNodesRestrictionsRange QueriesNotesKnown File TypesCustom Image Labeling (Optional)It is recommended to use this API in aJupyter Notebook, as the results from most
endpoints
are aDataFramewhich can be neatly displayed and efficiently manipulated with vectorized ops. This becomes
increasingly important if you have "large" amounts of data (e.g. >1 million photos/videos).Installationpipinstallamazon-photos-UOutput Examplesap.dbdateTimeDigitizedidname...modelapertureValuefocalLengthwidthheightsize02019-07-06T18:22:00.000ZHeMReF-vvJiTTkdPIeWuoP1694252973839.png...iPhone XS54823/3232517/43024403243277712023-01-18T09:36:22.000Zz_HiIvASAKqWmdrkjWiqMZ1692626817154.jpg...iPhone XS54823/3232517/43024403223425722022-08-14T14:13:21.000ZLKXEZbqoVrhrOYBezisGEQ1798219686789.jpg...iPhone 11 Pro Max54823/3232517/43024403242398732020-06-28T19:32:30.000ZEPUeciHtfKkGiYkfUyEuMa1593482220567.jpg...iPhone XS54823/3232517/43024403289895742021-07-07T17:12:55.000ZfdfKzRJbEyoVeGcfCoJgE-1592299282720.png...iPhone XR54823/3232517/43024403243255652021-08-18T18:32:41.000ZcrskJSmKPFRhxbpfkivyLm1592902159105.png...iPhone XR54823/3232517/43024403212312362023-08-23T19:12:21.000ZqkBFUlyIdkUwVVSaVWWKEF1598138358650.png...iPhone 1154823/3232517/43024403243788772021-06-19T17:14:13.000ZTXKMKC-mHvSUrtRfwmtyDe1622199863606.jpg...iPhone 12 Pro14447/1065321/51536204875843282023-02-15T22:45:40.000ZFRDvvjcZdpFWiwrIZfTNHO1581874518054.jpg...iPhone 8 Plus54823/32325399/10013482049862883ap.print_tree()~ 
├── Documents 
├── Pictures 
│   ├── iPhone 
│   └── Web 
│       ├── foo 
│       └── bar
├── Videos 
└── Backup 
    ├── LAPTOP-XYZ 
    │   └── Desktop 
    └── DESKTOP-IJK 
        └── DesktopSetup[Update] Jan 04 2024: To avoid confusion, setting env vars is no longer supported. One must pass cookies directly as
shown below.Log in to Amazon Photos and copy the following cookies:session-idubid*at*Canada/Europewherexxis the TLD (top-level domain)ubid-acbxxat-acbxxUnited Statesubid_mainat_mainE.g.fromamazon_photosimportAmazonPhotosap=AmazonPhotos(## US# cookies={#     'ubid_main': ...,#     'at_main': ...,#     'session-id': ...,# },## Canada# cookies={#     'ubid-acbca': ...,#     'at-acbca': ...,#     'session-id': ...,# }## Italy# cookies={#     'ubid-acbit': ...,#     'at-acbit': ...,#     'session-id': ...,# })ExamplesA database namedap.parquetwill be created during the initial setup. This is mainly used to reduce upload conflicts
by checking your local file(s) md5 against the database before sending the request.fromamazon_photosimportAmazonPhotosap=AmazonPhotos(# see cookie examples abovecookies={...},# optionally cache all intermediate JSON responsestmp='tmp',# pandas optionsdtype_backend='pyarrow',engine='pyarrow',)# get current usage statsap.usage()# get entire Amazon Photos librarynodes=ap.query("type:(PHOTOS OR VIDEOS)")# query Amazon Photos library with more filters appliednodes=ap.query("type:(PHOTOS OR VIDEOS) AND things:(plant AND beach OR moon) AND timeYear:(2023) AND timeMonth:(8) AND timeDay:(14) AND location:(CAN#BC#Vancouver)")# sample first 10 nodesnode_ids=nodes.id[:10]# move a batch of images/videos to the trash binap.trash(node_ids)# get trash bin contentsap.trashed()# permanently delete a batch of images/videosap.delete(node_ids)# restore a batch of images/videos from the trash binap.restore(node_ids)# upload media (preserves local directory structure and copies to Amazon Photos root directory)ap.upload('path/to/files')# download a batch of images/videosap.download(node_ids)# convenience method to get photos onlyap.photos()# convenience method to get videos onlyap.videos()# get all identifiers calculated by Amazon.ap.aggregations(category="all")# get specific identifiers calculated by Amazon.ap.aggregations(category="location")SearchUndocumented API, current endpoints valid Dec 2023.For validlocationandpeopleIDs, see the results from theaggregations()method.nametypedescriptionContentTypestr"JSON"_int1690059771064assetstr"ALL""MOBILE""NONE"DESKTOP"default:"ALL"filtersstr"type:(PHOTOS OR VIDEOS) AND things:(plant AND beach OR moon) AND timeYear:(2019) AND timeMonth:(7) AND location:(CAN#BC#Vancouver) AND people:(CyChdySYdfj7DHsjdSHdy)"default:"type:(PHOTOS OR VIDEOS)"groupByForTimestr"day""month""year"limitint200lowResThumbnailstr"true""false"default:"true"resourceVersionstr"V2"searchContextstr"customer""all""unknown""family""groups"default:"customer"sortstr"['contentProperties.contentDate DESC']""['contentProperties.contentDate ASC']""['createdDate DESC']""['createdDate ASC']""['name DESC']""['name ASC']"default:"['contentProperties.contentDate DESC']"tempLinkstr"false""true"default:"false"NodesDocs last updated in 2015FieldNameFieldTypeSort AllowedNotesisRootBooleanOnly lower case"true"is supported.nameStringYesThis field does an exact match on the name and prefix query. Considernode1{ "name" : "sample" }node2 { "name" : "sample1" }Query filtername:samplewill return node1name:sample*will return node1 and node2kindStringYesTo search for all the nodes which contains kind as FILEkind:FILEmodifiedDateDate (in ISO8601 Format)YesTo Search for all the nodes which has modified from timemodifiedDate:{"2014-12-31T23:59:59.000Z" TO *]createdDateDate (in ISO8601 Format)YesTo Search for all the nodes created oncreatedDate:2014-12-31T23:59:59.000ZlabelsString ArrayOnly Equality can be tested with arrays.if labels contains["name", "test", "sample"].Label can be searched for name or combination of values.To get all the labels which contain name and testlabels: (name AND test)descriptionStringTo Search all the nodes for description with value 'test'description:testparentsString ArrayOnly Equality can be tested with arrays.if parents contains["id1", "id2", "id3"].Parent can be searched for name or combination of values.To get all the parents which contains id1 and id2parents:id1 AND parents:id2statusStringYesFor searching nodes with AVAILABLE status.status:AVAILABLEcontentProperties.sizeLongYescontentProperties.contentTypeStringYesIf prefix query, only the major content-type (e.g.image*,video*, etc.) is supported as a prefix.contentProperties.md5StringcontentProperties.contentDateDate (in ISO8601 Format)YesRangeQueries and equals queries can be used with this fieldcontentProperties.extensionStringYesRestrictionsMax # of Filter Parameters Allowed is 8Filter TypeFiltersEqualitycreatedDate, description, isRoot, kind, labels, modifiedDate, name, parentIds, statusRangecontentProperties.contentDate, createdDate, modifiedDatePrefixcontentProperties.contentType, nameRange QueriesOperationSyntaxGreaterThan{"valueToBeTested" TO *}GreaterThan or Equal["ValueToBeTested" TO *]LessThan{* TO "ValueToBeTested"}LessThan or Equal{* TO "ValueToBeTested"]Between["ValueToBeTested_LowerBound" TO "ValueToBeTested_UpperBound"]Noteshttps://www.amazon.ca/drive/v1/batchLinkThis endpoint is called when downloading a batch of photos/videos in the web interface. It then returns a URL to
download a zip file, then makes a request to that url to download the content.
When making a request to download data for 1200 nodes (max batch size), it turns out to be much slower (~2.5 minutes)
than asynchronously downloading 1200 photos/videos individually (~1 minute).Known File TypesExtensionCategory.pdfpdf.docdoc.docxdoc.docmdoc.dotdoc.dotxdoc.dotmdoc.asddoc.cnvdoc.mp3mp3.m4amp3.m4bmp3.m4pmp3.wavmp3.aacmp3.aifmp3.mpamp3.wmamp3.flacmp3.midmp3.oggmp3.xlsxls.xlmxls.xllxls.xlcxls.xarxls.xlaxls.xlbxls.xlsbxls.xlsmxls.xlsxxls.xltxls.xltmxls.xltxxls.xlwxls.pptppt.pptxppt.ppappt.ppamppt.pptmppt.ppsppt.ppsmppt.ppsxppt.potppt.potmppt.potxppt.sldmppt.sldxppt.txttxt.texttxt.rtftxt.xmlmarkup.htmmarkup.htmlmarkup.zipzip.rarzip.7zzip.jpgimg.jpegimg.pngimg.bmpimg.gifimg.tifimg.svgimg.mp4vid.m4vvid.qtvid.movvid.mpgvid.mpegvid.3g2vid.3gpvid.flvvid.f4vvid.asfvid.avivid.wmvvid.swfexe.exeexe.dllexe.axexe.ocxexe.rpmexeCustom Image Labeling (Optional)Categorize your images into folders using computer vision models.pipinstallamazon-photos[extras]-USee theModel Listfor a list of all available models.Sample ModelsVery Largeeva02_base_patch14_448.mim_in22k_ft_in22k_in1kLargeeva02_large_patch14_448.mim_m38m_ft_in22k_in1kMediumeva02_small_patch14_336.mim_in22k_ft_in1k
vit_base_patch16_clip_384.laion2b_ft_in12k_in1k
vit_base_patch16_clip_384.openai_ft_in12k_in1k
caformer_m36.sail_in22k_ft_in1k_384Smalleva02_tiny_patch14_336.mim_in22k_ft_in1k
tiny_vit_5m_224.dist_in22k_ft_in1k
edgenext_small.usi_in1k
xcit_tiny_12_p8_384.fb_dist_in1krun('eva02_base_patch14_448.mim_in22k_ft_in22k_in1k',path_in='images',path_out='labeled',thresh=0.0,# threshold for predictions, 0.9 means you want very confident predictions onlytopk=5,# window of predictions to check if using exclude or restrict, if set to 1, only the top prediction will be checkedexclude=lambdax:re.search('boat|ocean',x,flags=re.I),# function to exclude classification of these predicted labelsrestrict=lambdax:re.search('sand|beach|sunset',x,flags=re.I),# function to restrict classification to only these predicted labelsdataloader_options={'batch_size':4,# *** adjust ***'shuffle':False,'num_workers':psutil.cpu_count(logical=False),# *** adjust ***'pin_memory':True,},accumulate=False,# accumulate results in path_out, if False, everything in path_out will be deleted before running againdevice='cuda',naming_style='name',# use human-readable label names, optionally use the label index or synsetdebug=0,)