Transitioning from API V2 to V3

API V3 is a ground-up redesign of the Alamy API. If you have an integration built against the legacy V2 (XML) Search API, this guide maps the concepts and parameters you know onto their V3 equivalents so you can plan the move.

The authoritative reference for every V3 endpoint, parameter and response shape is the API Reference. This guide is the bridge from V2 to that reference.

What changed at a glance

Area	V2 (legacy)	V3
Base URL	https://api.alamy.com/images/api/v2/	https://api.alamy.com/v3
Authentication	A uid GUID supplied by Alamy, appended to the query string	OAuth 2.0 client credentials — exchange your key & secret for a JWT bearer token
Response format	XML (<IMAGES>, <IMG-DETAIL>)	JSON, following the IPTC NinJS 2.0 standard
Search	GET /search?qt=…	GET /search?q=…
Single item metadata	GET /details?ImageID=…	GET /item/{id}
Multiple item metadata	(not available)	GET /item?ids=… (up to 500 ids)
Download	GET /download?ImgId=…&ImgBin=…	GET /download/{id} and POST /download/{id} for licensed downloads
Filter values	Numeric bitmasks / hex codes, combined by addition (e.g. ot=2&ot=4, et=0x…4008)	Named values in comma-separated lists (e.g. orientation=portrait,panoramic)

Authentication is now required

V2 identified you with a uid GUID on the query string. V3 uses OAuth 2.0 with the client credentials grant: you exchange your API key and secret at the token endpoint for a short-lived JWT, then send that as a Bearer token on every request. See Getting Started for where to find your key and secret. Anything V2 achieved by removing or supplying the uid (customised results, "Your Library" flags) is now driven by your authenticated account rather than a query-string parameter.

Responses are JSON, not XML

Where V2 returned <I> and <IMG-DETAIL> XML nodes with attributes such as AR, LI, PR and MR, V3 returns JSON news-item documents following IPTC NinJS 2.0. Search returns a partial metadata document per item; call the item endpoint for the complete metadata. Preview and thumbnail image URLs are part of the item metadata response — you no longer construct them from a geolocation host pattern (apic/apih/apil with /thumbs/ or /zooms/).

Search filter mapping

Every V2 search filter and its V3 equivalent. Where V2 used numeric codes or hex bitmasks, V3 takes human-readable values; multiple selections are a comma-separated list rather than bitmask addition.

Purpose	V2 parameter	V3 parameter
Search term	qt=elephant	q=elephant (required)
Results per page	pgs=0…7 (fixed sizes) or ipp= (max 100)	limit= (max 100, default 100)
Paging position	pn= (page number)	offset= (item offset, default 0)
License type	lic=1 (RF), lic=2 (RM)	licenseType=rf, licenseType=rm (omit for both)
Property release	pr=1	propertyRelease=true
Model release	mr=1	modelRelease=true
Orientation	ot=1/2/4/8 (landscape/portrait/panoramic/square)	orientation=landscape,portrait,panoramic,square
Number of people	hc=1…5	numberPeople=1,2,3,4,5 (5 = five or more)
Image type	imgt=1/2/8/4 (photo/illustration/vector/cutout)	type=photograph,illustration,vector,threesixty
Ethnicity	et=0x… (hex bitmask)	ethnicity=Indian,Brazilian (named values)
Age	ag=… (bitmask)	age=twenties,child (named values)
Viewpoint	vp=1/2/4/8 (front/side/rear/profile)	viewpoint=front,side,rear,profile
Date taken (from)	dtfr=YYYYMMDD	dateCreatedSince=YYYY-MM-DD (ISO 8601)
Date taken (to)	dtto=YYYYMMDD	dateCreatedBefore=YYYY-MM-DD (ISO 8601)
Date taken (exact)	dtfr=…&dtto=… (same date)	dateCreated=YYYY-MM-DD
More by this pseudonym	st=9&pseudoid=…	by=<photographer or contributor name>
Contributor name in results	cl=1	Contributor / credit information is part of the standard NinJS response
Customised results	uid=<GUID>	Driven by your authenticated account (no parameter)

Filters removed in V3

These V2 filters have no direct V3 equivalent:

• Minimum file size (size=0x…) — image size filtering by megabytes is not offered on the V3 search.
• Location (loc=1/2/4, USA/UK/Europe) — see the territory note below.
• Cut out (imgt=4) as a modifier — V3 offers a threesixty type instead.

New in V3

Filters V2 never had, worth knowing about when you rebuild:

• searchMode — text (default), semantic (visual match), hybrid, or smart (auto-select).
• order — sort by relevant (default), newest, newest-datetaken, oldest-datetaken, creative.
• includeCategory — filter to Alamy content categories (e.g. Concepts,Education).
• collectiontype — filter by collection (ultimate, vital, editorial-core, …).
• library — restrict to your iq or discount library (the V2 APALIB response flag).
• safe, exclusive, blackAndWhite — boolean quality/scope filters.
• Video: resolution, frameRate, durationStart, durationEnd.

Common questions

How is DATETAKEN represented in the V3 API?

In V2 the image's capture date came back as the DATETAKEN attribute (yyyymmdd). In V3 the contentcreated field represents the date the content was created, and it is filtered with dateCreated, dateCreatedSince and dateCreatedBefore (ISO 8601 dates).

Where do I provide the territory parameter?

Providing a territory filter is no longer supported in Alamy API V3. This has been abstracted to the account management layer and will be applied, if necessary, during account setup. If you require changes to this at any point please contact your Alamy Account Manager.

Is the V3 dateCreated filter equivalent to the V2 "Date taken" filter?

Yes — the same concept, with clearer parameter names:

• The V2 dtfr (date from) filter is now dateCreatedSince.
• The V2 dtto (date to) filter is now dateCreatedBefore.
• dateCreated allows filtering on an exact date.

Examples can be found in the search endpoint reference.

Which Alamy IDs can I use?

V3 accepts both the seq (sequence, e.g. 34337802) and ref (reference, e.g. BYT662) forms on the item and search endpoints. The download endpoint supports the sequence form. See also Which Alamy IDs are supported by the API? in the general FAQ.