Home

CityGrid Advertising APIs

Skip to end of metadata
Go to start of metadata

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). 

Contents

 

Get Endpoint

 

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

 

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

placesPlace 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_idStringProvider 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_typePROFILEImage type relative to the place.  Current implementation supports only Place Profile Images (profile slideshow).
Additional image types may be implemented later. 
image_nameStringName 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
XML Response
JSON Error Response (single place error, full request SUCCESS)
JSON Error Response (full request error)
XML Error Reponse

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:

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
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

Property

Type

Description

response

Response Metadata

(See complete response descriptions)

external_place_idStringThe external place identifier

place_id

Long

The CGM ID of the place

image_pathStringURL of the image that was manipulated
image_nameStringName given to the image
image_typePROFILEImage 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
Example 2: An XML Response
Example 4: Single Operation failure
Example 5: Request failure
  • No labels