Places Image Management API

Introduction

The CityGrid Places Image Management API is part of the Advertising by CityGrid suite of APIs and allows developers to retrieve, create and update the set of images related to places in the CGM advertising platform. Note that this API relates hosted images to a Place, but does not provide image hosting itself (i.e. the API takes a full URL path for an image that is already hosted).

Get Endpoint

The CityGrid Places Get API allows users to retrieve information regarding places images. Response formats include XML and JSON.

https://api.citygrid.com/content/places/images/v1/get

Please note that the API requires https.

Request Parameters

Field	Type	Description	Required	Examples
`external_place_ids`	Comma separated listing if String values	A list of External IDs to be resolved to places	Required if no place_ids are specified	183765, mar_biz6368
`place_ids`	Comma-separated list of Long values	List of places IDs	Required as an alternate for external_place_id. If external_place_id also specified, external_place_id takes precedence of place_id.	11790182,12314

Request Example

https://api.citygridmedia.com/content/places/images/v1/get?external_place_ids=4320920_a,5320920_a

Description	Endpoint
Get Places by External Place IDs

Get Header values

Name	Values	Description
Content-Type	Application/JSON Application/XML	Return format. Content-Type and Accept must match
Accept	Application/JSON Application/XML	Return format. Content-Type and Accept must match
authToken	Authentication Token from Authentication API	Required

Response Properties

Outer Response

Field	Type	Description
totalNumEntries	Integer	The number of places represented in the response
places	Place list (see next table)	A list of Places and their associated images
response	(See complete response descriptions)	Response status for the request

Places - Each place element in the places list contains the following

Field	Type	Description
external_place_id	String	Provider specific external ID to a place
place_id	Integer	Internal CGM ID for the same place
images	Image List (see next table)	The list of images related to the corresponding place
response	(See complete response descriptions)	Response status for the individual place within the request

Image - Each image in a place's images list contains the following

Field	Type	Description
image_path	String	Full url path of image location (including http or https prefix)
image_type	PROFILE	Image type relative to the place. Current implementation supports only Place Profile Images (profile slideshow). Additional image types may be implemented later.
image_name	String	Name given to image
is_primary	[Y \| N ]	Indicates if the image is the Primary Profile Image for the corresponding place

Media Types Supported

Header	Type
Content Type	Application/JSON
	Application/XML
Accept	Application/JSON
	Application/XML

GET Response Example

request: https://api.citygrid.com/content/places/images/v1/get?external_place_ids=37179303, 7777777

JSON Response

{
  "totalNumEntries": 2,
  "places": [
    {
      "place_id": "902504099",
      "external_place_id": "37179303",
      "images": [
        {
          "image_path": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcQS6VO6tIUWgYOPDcV6rFFMreLVuyBfhrNCPd7v4s8LZ6-iAxRf",
          "image_type": "PROFILE",
          "image_name": "Lux Rental",
          "is_primary": "0"
        },
        {
          "image_path": "http://t3.gstatic.com/images?q=tbn:ANd9GcTmkcfyOXnS9UqAIw22JhHAZU_ZiDbRaUBp8HAMcmz3zjxCnlaKmA",
          "image_type": "PROFILE",
          "image_name": "Showroom",
          "is_primary": "1"
        }
      ],
      "response": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
      }
    },
    {
      "place_id": "7777777",
      "external_place_id": "7777777",
      "images": [
        {
          "image_path": "http://images.citysearch.net/assets/imgdb/merchant/2014/2/10/0/rEisvJog10.jpeg",
          "image_type": "PROFILE",
          "image_name": "Cars R Us",
          "is_primary": "1"
        },
        {
          "image_path": "http://images.citysearch.net/assets/imgdb/merchant/2014/2/10/0/YMhgQMCO12.jpeg",
          "image_type": "PROFILE",
          "image_name": "Lot 1",
          "is_primary": "0"
        },
        {
          "image_path": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcQS6VO6tIUWgYOPDcV6rFFMreLVuyBfhrNCPd7v4s8LZ6-iAxRf",
          "image_type": "PROFILE",
          "image_name": "Westside",
          "is_primary": "0"
        }
      ],
      "response": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
      }
    }
  ],
  "response": {
    "code": "SUCCESS",
    "message": "Success",
    "field": ""
  }
}

XML Response

<results>
    <totalNumEntries>2</totalNumEntries>
    <places>
        <place>
            <place_id>902504099</place_id>
            <external_place_id>37179303</external_place_id>
            <images>
                <image>
                    <image_path>
                        https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcQS6VO6tIUWgYOPDcV6rFFMreLVuyBfhrNCPd7v4s8LZ6-iAxRf
                    </image_path>
                    <image_type>PROFILE</image_type>
                    <image_name>Lux Rental</image_name>
                    <is_primary>0</is_primary>
                </image>
                <image>
                    <image_path>
                        http://t3.gstatic.com/images?q=tbn:ANd9GcTmkcfyOXnS9UqAIw22JhHAZU_ZiDbRaUBp8HAMcmz3zjxCnlaKmA
                    </image_path>
                    <image_type>PROFILE</image_type>
                    <image_name>Showroom</image_name>
                    <is_primary>1</is_primary>
                </image>
            </images>
            <response>
                <code>SUCCESS</code>
                <field/>
                <message>Success</message>
            </response>
        </place>
        <place>
            <place_id>7777777</place_id>
            <external_place_id>7777777</external_place_id>
            <images>
                <image>
                    <image_path>
                        http://images.citysearch.net/assets/imgdb/merchant/2014/2/10/0/rEisvJog10.jpeg
                    </image_path>
                    <image_type>PROFILE</image_type>
                    <image_name>Cars R Us</image_name>
                    <is_primary>1</is_primary>
                </image>
                <image>
                    <image_path>
                        http://images.citysearch.net/assets/imgdb/merchant/2014/2/10/0/YMhgQMCO12.jpeg
                    </image_path>
                    <image_type>PROFILE</image_type>
                    <image_name>Lot 1</image_name>
                    <is_primary>0</is_primary>
                </image>
                <image>
                    <image_path>
                        https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcQS6VO6tIUWgYOPDcV6rFFMreLVuyBfhrNCPd7v4s8LZ6-iAxRf
                    </image_path>
                    <image_type>PROFILE</image_type>
                    <image_name>Westside</image_name>
                    <is_primary>0</is_primary>
                </image>
            </images>
            <response>
                <code>SUCCESS</code>
                <field/>
                <message>Success</message>
            </response>
        </place>
    </places>
    <response>
        <code>SUCCESS</code>
        <field/>
        <message>Success</message>
    </response>
</results>

JSON Error Response (single place error, full request SUCCESS)

{
  "totalNumEntries": 2,
  "places": [
    {
      "place_id": "",
      "external_place_id": "765",
      "images": [],
      "response": {
        "code": "ENTITY_NOT_FOUND",
        "message": "The place could not be found.",
        "field": ""
      }
    },
    {
      "place_id": "7777777",
      "external_place_id": "7777777",
      "images": [
        {
          "image_path": "http://images.citysearch.net/assets/imgdb/merchant/2014/2/10/0/rEisvJog10.jpeg",
          "image_type": "PROFILE",
          "image_name": "Cars R Us",
          "is_primary": "1"
        },
        {
          "image_path": "http://images.citysearch.net/assets/imgdb/merchant/2014/2/10/0/YMhgQMCO12.jpeg",
          "image_type": "PROFILE",
          "image_name": "Lot 1",
          "is_primary": "0"
        },
        {
          "image_path": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcQS6VO6tIUWgYOPDcV6rFFMreLVuyBfhrNCPd7v4s8LZ6-iAxRf",
          "image_type": "PROFILE",
          "image_name": "Westside",
          "is_primary": "0"
        }
      ],
      "response": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
      }
    }
  ],
  "response": {
    "code": "SUCCESS",
    "message": "Success",
    "field": ""
  }
}

JSON Error Response (full request error)

{
  "totalNumEntries": 0,
  "places": [],
  "response": {
    "code": "PARAMETER_REQUIRED",
    "message": "The parameter, place_ids or external_place_ids, is required but has not been supplied.",
    "field": "place_ids or external_place_ids"
  }
}

XML Error Reponse

 <results>
    <totalNumEntries>0</totalNumEntries>
    <places/>
    <response>
        <code>PARAMETER_REQUIRED</code>
        <field>place_ids or external_place_ids</field>
        <message>The parameter, place_ids or external_place_ids, is required but has not been supplied.</message>
    </response>
</results>

Mutate Endpoint

The places/images/mutate endpoint allows users to create, update, and remove images related to places. The operation is invoked via HTTPS POST to:

https://api.citygrid.com/content/places/images/v1/mutate

Input data such as request parameters are subject to field size limits.

Image Size

Currently this API only supports Places Profile Images. When displayed, profile images will be scaled to fit 380x285, so it is recommended that your images maintain this dimension ratio to properly fill the profile image spaces on various websites. Smaller images may appear grainy when scaled up. Because proportions are kept when re-sizing images, if an image is in a portrait orientation, there may be extra space around the edges of your images when displayed.

Request Parameters

The mutate operations available on places are:

The ADD operator, ads an image to a place .
The SET operator, is used to change attributes on an existing image (i.e. change which image is the Primary Profile Image or change the image_name)
The Remove operator, is used to remove an image from a place.

Every places/images/mutate request requires the following two parameters:

Property	Type	Description	Required
`operator`	{ADD, SET, REMOVE}	Type of operation to perform (case sensitive)	Yes
`operand`	Place Image Details	The place and image to operate on	Yes

The properties of an Operand object in a request are:

Field	Description	Required	Type	Examples	Limit
`external_place_id`	Your own ID for a place. Cannot be deleted. Used for referencing the place.	Required if `place_id` is not specified. Use of an external_place_id is recommended over using the CGM place_id. External place IDs take precedence over CGM place IDs when both are specified.	String	183268 mar_biz133	255 chars
`place_id`	The ID of the place in the CityGrid ID space. Cannot be deleted.	Required if `external_place_id` is not specified. External place IDs take precedence over CGM place IDs when both are specified.	Long	1231231
`image_path`	Full URL path to image (including http or https prefix). Images are identified uniquely by their full image path/url.	Yes, and the path must point to an existing GIF or JPEG image. If an image does not exist at the location specified, the API operation will fail. Note that the file extension is not required, but proper format is. See for mare details on suggested image sizes.	path to a GIF or JPEG file	http://www.myomagehos.com/path/smiley.jpg https://my.image.com/q=tbn:ANd9	2000 chars
`image_type`	Type of image relative to the place. Currently the API supports only PROFILE images, but new image types may be introduced in the future.	Yes	PROFILE	PROFILE	PROFILE only
`image_name`	A name give to the image. The name does not need to be unique. Currently this name is not published but may be in the future. In the meantime it can be used for the customer's own reference.	No, however if no image name is specified on ADD operation, a default image name will be created based on the related place business name.	String	Sam's Ice Cream Showroom Floor	60 chars
`is_primary`	Whether the image should be displayed as the primary profile image (1=Yes, 0=No). When one image is set as is_primary=1, all other images related to the same place will become is_primary=0. As such the last image set to is_primary=1 in a request will be the primary profile image for the place.	Required for ADD operation.	{0, 1}

Request Header Values

Header	Description	Required	Valid Values
`Content-Type`	Media type of the request body	Yes	`application/json` `application/xml`
`Accept`	Requested format for the response	Yes	`application/json` `application/xml`
`authToken`	Authentication Token from the Authentication API	Yes	Valid token
`developerToken`	The token received during registration	Yes	Valid token

Request Examples

Example 1: A JSON ADD Example

{"mutateOperationListResource":[
    {   "operator":"ADD",
        "operand":{ 
           "place_id":"7777777",
           "is_primary":"0",
           "image_path":"http://images.citysearch.net/assets/imgdb/merchant/2014/2/10/0/rEisvJog10.jpeg",
           "image_name":"Profile Image",
           "image_type":"PROFILE"
        }
    },
   {    "operator":"ADD",
        "operand":{ 
           "place_id":"7777777",
           "is_primary":"1",
           "image_path":"http://images.citysearch.net/assets/imgdb/merchant/2014/2/10/0/YMhgQMCO12.jpeg",
           "image_name":"Main Entrance",
           "image_type":"PROFILE"
        }
   }
]}

Example 2: A JSON SET Example

{"mutateOperationListResource":[
    {   "operator":"SET",
        "operand":{ 
           "place_id":"7777777",
           "is_primary":"1",
           "image_path":"http://images.citysearch.net/assets/imgdb/merchant/2014/2/10/0/rEisvJog10.jpeg",
           "image_name":"Profile Image",
           "image_type":"PROFILE"
        }
    },
   {    "operator":"SET",
        "operand":{ 
           "place_id":"7777777",
           "is_primary":"0",
           "image_path":"http://images.citysearch.net/assets/imgdb/merchant/2014/2/10/0/YMhgQMCO12.jpeg",
           "image_name":"Side Entrance",
           "image_type":"PROFILE"
        }
   }
]}

Example 3: A JSON Multi-Operation Example (ADD, SET and REMOVE)

{"mutateOperationListResource":[
    {   "operator":"ADD",
        "operand":{ 
           "place_id":"7777777",
           "is_primary":"0",
           "image_path":"http://images.citysearch.net/assets/imgdb/merchant/2014/2/10/0/rEisvJog10.jpeg",
           "image_name":"Profile Image",
           "image_type":"PROFILE"
        }
    },
   {    "operator":"SET",
        "operand":{ 
           "place_id":"7777777",
           "is_primary":"1",
           "image_path":"http://images.citysearch.net/assets/imgdb/merchant/2014/2/10/0/YMhgQMCO12.jpeg",
           "image_name":"New Main Entrance",
           "image_type":"PROFILE"
        }
   },
   {    "operator":"REMOVE",
        "operand":{ 
           "place_id":"7777777",
           "image_path":"https://encrypted-tbn2.gstatic.com/images?q=t-mq3VQX6P-_UswKswzl-V5GiQ4NXNvR",
           "image_name":"Main Entrance Old",
           "image_type":"PROFILE"
        }
   }
]}

Example 4: An XML Multi-Operation Example (SET and ADD)

<mutateOperationListResource>
    <mutateOperation>
        <operator>SET</operator>
        <operand>
            <external_place_id>7777777</external_place_id>
            <image_path>http://images.citysearch.net/assets/imgdb/merchant/2014/2/10/0/YMhgQMCO12.jpeg</image_path>
            <image_type>PROFILE</image_type>
            <image_name>New Name</image_name>
        </operand>
    </mutateOperation>
    <mutateOperation>
        <operator>ADD</operator>
        <operand>
            <external_place_id>7777777</external_place_id>
            <image_path>http://images.citysearch.net/assets/imgdb/merchant/2014/2/10/0/rEisvJog10.jpeg</image_path>
            <image_type>PROFILE</image_type>
            <image_name>New Image</image_name>
            <is_primary>1</is_primary>
        </operand>
    </mutateOperation>
</mutateOperationListResource>

Response Properties

Property	Type	Description
`response`	Response Metadata	(See complete response descriptions)
`external_place_id`	String	The external place identifier
`place_id`	Long	The CGM ID of the place
`image_path`	String	URL of the image that was manipulated
`image_name`	String	Name given to the image
`image_type`	PROFILE	Image type relative to the place. Current implementation supports only Place Profile Images (profile slideshow). Additional image types may be implemented later.

Note that the properties included in the response are to help identify the status of the operations in the request. As such the is_primary flag is not included in the response as it is not an identifier and may actually change within a single set of submitted operations.

Response Examples

Example 1: A JSON Response

{
  "resources": [
    {
      "response": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
      },
      "place_id": "7777777",
      "external_place_id": "7777777",
      "image_path": "http://images.citysearch.net/assets/imgdb/merchant/2014/2/10/0/rEisvJog10.jpeg",
      "image_type": "PROFILE",
      "image_name": "Profile Image"
    },
    {
      "response": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
      },
      "place_id": "7777777",
      "external_place_id": "7777777",
      "image_path": "http://images.citysearch.net/assets/imgdb/merchant/2014/2/10/0/YMhgQMCO12.jpeg",
      "image_type": "PROFILE",
      "image_name": "Main Entrance"
    }
  ]
}

Example 2: An XML Response

<placeList>
    <resource>
        <external_place_id>7777777</external_place_id>
        <image_path>
            http://images.citysearch.net/assets/imgdb/merchant/2014/2/10/0/rEisvJog10.jpeg
        </image_path>
        <place_id>7777777</place_id>
        <response>
            <code>SUCCESS</code>
            <field/>
            <message>Success</message>
        </response>
    </resource>
    <resource>
        <external_place_id>7777777</external_place_id>
        <image_path>
            http://images.citysearch.net/assets/imgdb/merchant/2014/2/10/0/YMhgQMCO12.jpeg
        </image_path>
        <place_id>7777777</place_id>
        <response>
            <code>SUCCESS</code>
            <field/>
            <message>Success</message>
        </response>
    </resource>
</placeList>

Example 4: Single Operation failure

{
  "resources": [
    {
      "response": {
        "code": "ENTITY_NOT_FOUND",
        "message": "The file designated by image_path could not be found.",
        "field": ""
      },
      "place_id": "7777777",
      "external_place_id": "",
      "image_path": "http://bad.imagelocation.com/notthere",
      "image_type": "PROFILE",
      "image_name": "Profile Image"
    },
    {
      "response": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
      },
      "place_id": "7777777",
      "external_place_id": "7777777",
      "image_path": "http://images.citysearch.net/assets/imgdb/merchant/2014/2/10/0/YMhgQMCO12.jpeg",
      "image_type": "PROFILE",
      "image_name": "Main Entrance"
    }
  ]
}

Example 5: Request failure

{
  "resources": [
    {
      "response": {
        "code": "INVALID_REQUEST_BODY",
        "message": "The request is malformed or invalid/deprecated operands/parameters with request.",
        "field": ""
      },
      "place_id": "",
      "external_place_id": "",
      "image_path": "",
      "image_type": "",
      "image_name": ""
    }
  ]
}

Places Image Management API

Introduction

Contents

Get Endpoint

Request Parameters

Request Example

Get Header values

Response Properties

Media Types Supported

GET Response Example

JSON Response

XML Response

JSON Error Response (single place error, full request SUCCESS)

JSON Error Response (full request error)

XML Error Reponse

Mutate Endpoint

Image Size

Request Parameters

Request Header Values

Request Examples

Example 1: A JSON ADD Example

Example 2: A JSON SET Example

Example 3: A JSON Multi-Operation Example (ADD, SET and REMOVE)

Example 4: An XML Multi-Operation Example (SET and ADD)

Response Properties

Response Examples

Example 1: A JSON Response

Example 2: An XML Response

Example 4: Single Operation failure

Example 5: Request failure