Event Images

The API provides a consistent interface for accessing listings images for events across all participating festivals, subject to availability.

Image types

The shape and size of source images varies by festival, depending on what the image was originally intended for. The type property of each image provides a hint as to intended use. You may also wish to check the orientation property as well as the width and height of the original image in order to filter out images that may not be in a suitable format for your use case.

You may only resize images in their original aspect ratio, and you must not crop images (automatically or manually) without advance permission.

Type Description
hero A large-format, generally landscape, image originally designed for display as the major feature element of a page. May be suitable as a thumbnail but requires careful handling in this case.
thumb A smaller, generally approximately square or portrait, image designed for display alongside other content on a page or as a thumbnail within listings results.

Image versions

In addition to the original format, we provide resized versions of each image. Small images will not be scaled up, so only the original, square-75 and square-150 versions are guaranteed to be present.

Version Key Width Height Description
original {varies} {varies} The original size and format of the image
square-75 75px 75px Scaled down to fit a transparent 75 pixel square box.
square-150 150px 150px Scaled down to fit a transparent 150 pixel square box.
thumb-100 One side 100px Scaled down in original aspect ratio to 100 pixels on the longest side.
small-320 One side 320px Scaled down in original aspect ratio to 320 pixels on the longest side.
medium-640 One side 640px Scaled down in original aspect ratio to 640 pixels on the longest side.
large-1024 One side 1024px Scaled down in original aspect ratio to 1024 pixels on the longest side.

Usage rights, hosting, linking and protocols

Most of the images are only approved for distribution as part of the participating festivals' marketing and promotion activity. You are welcome to use and display the provided images alongside both historical and active listings content, generally accompanied by at least the name of and link to the festival website. Use of the images independently may be a breach of copyright. We are working on more specific guidance, but in the meantime if you are not sure whether your proposed image usage meets these requirements please contact us to discuss.

Heads up! Beginning in Jan 2024 image URLs for events will now be fully qualified with https://

The API response for events prior to 2024 returns a scheme-relative URL - eg //images.api.edinburghfestivalcity.com/ab/cd/ef/9948272323-original.jpg. This URL format will trigger browsers to automatically use either HTTP or HTTPS depending on whether the connection to your own server was over a secure connection. Some parsing libraries (including PHP) do not properly recognise scheme-relative URLs so you may find you need to add the appropriate http: or https: prefix for machine usage.

For low and medium traffic applications, you are welcome to serve the provided URLs directly in your application or website, subject to the normal API terms and conditions. If you are operating a high traffic site we ask that you contact us to discuss fair usage and any bandwidth limitations before launching your site.