Deep Zoom API

Note This information is only intended for partnering organizations who have entered into record sharing agreements with FamilySearch.Deep Zoom allows users to zoom in on a large, high-resolution image or a collection of images. Images are broken into tiles and then displayed as required. This reduces the time required for initial load by downloading only the region being viewed and/or only at the resolution at which it is being displayed. Subsequent regions are downloaded as the user pans to or zooms into them. Follow the steps below to use the API.

Deep Zoom Images

A Deep Zoom Image (DZI) has two parts: a DZI file and a subdirectory of image files. Each image in the subfolder directory is labeled with its level of resolution. Higher numbers correspond to a higher resolution level.

Step 1: Request an access token.

This can be an unauthenticated access token. For information on getting an access token, see the Authentication guide.

Step 2: Request the DZI document.

You should have a PAL URI from the record data that represents an image resource. The DZI document describes the format, level, width, height and overlap attribute of an image. With this information, a Deep Zoom client is able to build a request for tiling. You will then need to get the image parameters from the DZI Document. To obtain the DZI document for each PAL, use this template: https://familysearch.org/{pal\_id}?dz=true. For example: https://familysearch.org/pal:/MM9.3.1/TH-1942-27750-552-7?dz=true.

Step 3: Send parameters to FamilySearch to retrieve tiles.

These parameters are used to retrieve the various tiles. The Deep Zoom client uses values from the DZI document to determine the level and the X and Y coordinates for each image. Once you have the level and coordinates, you can build the tile URLs based on this template: https://familysearch.org/{pal\_id}/image\_files/{level}/{x}\_{y}.jpg?{dz,access\_token}.

For example: https://familysearch.org/pal:/MM9.3.1/TH-1942-27750-552-7/image\_files/11/5934\_4481.jpg?/dz=true&access\_token=USYS2BFC65091708FC20F656E8CC6178FB09\_idsesprod01.a.fsglobal.net.