API Docs
Support

Places Photos Guide

Use endpoints like Place Search, Place Details, and Place Photos to retrieve components of a photo URL that can be quickly assembled to get a photo.

Response Fields

FieldDescription
idA unique identifier for this photo.
created_atThe date and time when this photo was created.
classificationsLabel(s) to help describe the contents of the photo.
prefixBeginning of the URL for this photo.
suffixEnding of the URL for this photo.
widthMaximum width of the photo, in pixels.
heightMaximum height of the photo, in pixels.

Sample JSON Response

This is a sample photo response from the Places API. This example will be used throughout this documentation.

"photos": [
{
  "id":"5183232a498ea9477d575e31",
  "created_at":"2013-05-03T02:38:34.000Z",
  "prefix":"https://fastly.4sqi.net/img/general/",
  "suffix":"/1049719_PiLE0Meoa27AkuLvSaNwcvswnmYRa0vxLQkOrpgMlwk.jpg",
  "width":1920,
  "height":1440,
  "classifications":[ "outdoor" ]
}

Assembling a Photo URL

We want to help you efficiently integrate photos into your applications while minimizing unnecessary data transfer. Below, find our recommended ways to assemble photo URLs:

Request Scaled Photos (Highly Recommended)

You should request scaled photos for most use cases, significantly reducing bandwidth consumption and improving the speed and user experience of your applications.

To request a scaled image, determine the width and height at which the image should be displayed in your application. Be sure to verify your width and height do not exceed the values in the metadata.

  • Assembly: prefix + {targetWidth}x{targetHeight} + suffix
  • Example (metadata):
    If you need to display this photo at a maximum width of 600 pixels, calculate the proportional height: (600 / 1920) * 1440 = 450. The scaled URL would be:
    https://fastly.4sqi.net/img/general/600x450/1049719_PiLE0Meoa27AkuLvSaNwcvswnmYRa0vxLQkOrpgMlwk.jpg
Scaled Example

Request Cropped Photos (For Specific Layouts)

Certain layouts require fixed aspect ratios (e.g. square). You can request a cropped version by specifying the desired size.

  • Assembly: prefix + {size}x{size} + suffix
  • Example (metadata):
    To get a 200x200 pixel square crop of the photo:
    https://fastly.4sqi.net/img/general/200x200/1049719_PiLE0Meoa27AkuLvSaNwcvswnmYRa0vxLQkOrpgMlwk.jpg

Cropped Image

Request Original Size

❗️

Use Original Image Size Responsibly

Requesting the original image size should be reserved for cases where full resolution is absolutely necessary.

Requesting scaled and cropped photos often results in the best user experience. Judicious use of photo requests ensures our systems are not degraded by excessive requests, aligning with our Acceptable Use policy.

If you need assistance scaling your images, we are more than happy to help in our Slack or Discord channels.


Requesting the original size should be reserved for cases where the full resolution is a requirement. For this example photo, the original size is 1920x1440, which can consume significant bandwidth.

  • Assembly: prefix + original + suffix
  • Example (metadata):
    To get an original sized version of the photo:
    https://fastly.4sqi.net/img/general/original/1049719_PiLE0Meoa27AkuLvSaNwcvswnmYRa0vxLQkOrpgMlwk.jpg

Original Image

Category Icons

Icons for categories may be returned in the categories response field and are structured in a similar prefix + size + suffix format. All icons are square images.

{
  "id":10001
  "name":"Amusement Park"
  "icon":{
    "prefix":"https://ss3.4sqi.net/img/categories_v2/arts_entertainment/themepark_"
    "suffix":".png"
  }
}

To obtain an icon, the only acceptable size values are one of: 32, 44, 64, 88, or 120 (pixels)

For example, the Amusement Park icon url is: https://ss3.4sqi.net/img/categories_v2/arts_entertainment/themepark_120.png

Additionally, a background can be added to any icon by adding bg_ to the URL (i.e. https://ss3.4sqi.net/img/categories_v2/arts_entertainment/themepark_bg_120.png)

Category Example