Home

CityGrid Advertising APIs

Skip to end of metadata
Go to start of metadata

Introduction

The CityGrid Offer API is part of the Advertising by CityGrid suite of APIs which allows developers to  manage the Deals and Special Offers shown on their campaign listing profile page as well as on deal and coupon sites. 

Contents


Offer Get Endpoint

The offer get endpoint retrieves information about a set of selected offers. The operation is invoked via HTTPS GET to:

Request Parameters

Parameter

Description

Required

Type

Default

Example

offerIds

Comma-separated list of offer IDs.

No

Comma separated list of Long values

798855,1334954

externalPlaceIds

Comma-separated list of external place IDs. Used to retrieve all offers related to each place indicated.

No

Comma separated list of Strings

BDF_Business1,BDF_Business33

placeIds

Comma-separated list of place IDs.  Used to retrieve all offers related to each place indicated.

No

Comma separated list of Long values

4784745,90095856,6758798

startIndex

Page number of results to return (zero-based)

No

Integer

0

5

numberResults

Number of results per page

No

Integer

10

25

accountId

The id of an account which owns listings related to the requested offers. An accountId is required only when the authenticated user is an internal CGM user in order to set the account context for the operation. If the logged in user is an external user (i.e. not an internal CGM employee) the accountId should not be specified.

No (See Description)Long304998

The GET response will be the union of all offers related to the offerIds, placeIds, and externalPlaceIds indicated.

 


Request Headers

Header

Description

Required

Valid Values

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: Get offers 122445872 and 121044952

 

curl -X GET \
    -H 'Accept:application/json' \
    -H 'authToken:mytoken' \

 

Example 2: Get the second page of five offers from all of the offers related to externalPlaceId=666666
Example 4: Get offers 122445872 and 121044952 in addition to ones related to externalPlaceId=666666

Get Offer Response Properties

Field 

Description 

Type 

responseThe structure and metadata for the entire response(See complete response descriptions)
totalNumEntriesIntegerTotal number of offers that match the criteria of the GET request across all pages
offersOffer listThe offers returned from the search, each containing the data elements below

places

List of places associated to the Offer

Array of place objects (see Places grid above for details)

offerId

The id of the offer

long

title

The text/title of the offer

String

description

The description of the offer

String

offerStatus

The status of the offer

ACTIVE|DISABLE

termsAndConditions

Terms and conditions associated to the offer

String

type

The type of the Offer

BUY_ONE_GET_ONE_FREE|DOLLARS_OFF|FREE|GIFT_WITH_PURCHASE|
OTHER|PERCENT_OFF|PURCHASE_WITH_PURCHASE

redemptionType

The redemption type of the offer

BOTH|ONLINE|PRINT

redemptionCode

The code of the redemption

String

redemptionUrl

The url of the redemption

String (in valid URL format)

imageUrl

The url of the image associated to the offer

String (in valid URL format)

imageNameA name related to the offer imageString

startDate

The start date of the offer

String (yyyyMMdd)

expirationDate

The expiration date of the offer

String (yyyyMMdd)

imageName

The name of the image associated to the offer

String

responseStatus

Response status

ResponseStatus 

Response Examples

Example 1: A JSON success response

 

{
  "totalNumEntries": 2,
  "offers": [
    {
      "places": [
        {
          "externalPlaceId": "606001882",
          "placeId": "444444"
        }
      ],
      "offerId": "122404712",
      "title": "%50 off Sale",
      "description": "%50 off everything in the store.",
      "offerStatus": "ACTIVE",
      "termsAndConditions": "While supplies last. Offer void for employees of the store, etc.",
      "type": "PERCENT_OFF",
      "redemptionType": "PRINT",
      "redemptionCode": "22",
      "redemptionUrl": "http://www.fakeurl.com",
      "imageName": "50 Percent Offer",
      "startDate": "20130501",
      "expirationDate": "20130530",
      "responseStatus": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
      }
    },
    {
      "places": [
        {
          "externalPlaceId": "666666",
          "placeId": "666666"
        },
        {
          "externalPlaceId": "606001882",
          "placeId": "444444"
        }
      ],
      "offerId": "122416972",
      "title": "75% Off Clearance Sale",
      "description": "Everything must go at %75 off!",
      "offerStatus": "ACTIVE",
      "termsAndConditions": "While supplies last. Offer void for employees of the store, etc.",
      "type": "PERCENT_OFF",
      "redemptionType": "PRINT",
      "redemptionCode": "33",
      "redemptionUrl": "http://www.fakeurl75.com",
      "imageName": "75 percent offer",
      "startDate": "20130601",
      "expirationDate": "",
      "responseStatus": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
      }
    }
  ]
}

 

Example 2: A XML success response

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<results>
  <totalNumEntries>2</totalNumEntries>
  <offers>
    <offer>
      <description>some description</description>
      <expirationDate>
      </expirationDate>
      <imageName>some title</imageName>
      <offerId>122404712</offerId>
      <offerStatus>ACTIVE</offerStatus>
      <places>
        <place>
          <externalPlaceId>606001882</externalPlaceId>
          <placeId>444444</placeId>
        </place>
      </places>
      <redemptionCode>22</redemptionCode>
      <redemptionType>PRINT</redemptionType>
      <redemptionUrl>http://www.fakeurl.com</redemptionUrl>
      <response>
        <code>SUCCESS</code>
        <field>
        </field>
        <message>Success</message>
      </response>
      <startDate>20111028</startDate>
      <termsAndConditions>terms and conditions test</termsAndConditions>
      <title>Make it so</title>
      <type>PERCENT_OFF</type>
    </offer>
    <offer>
      <description>some description</description>
      <expirationDate>
      </expirationDate>
      <imageName>some title</imageName>
      <offerId>122416972</offerId>
      <offerStatus>ACTIVE</offerStatus>
      <places>
        <place>
          <externalPlaceId>666666</externalPlaceId>
          <placeId>666666</placeId>
        </place>
        <place>
          <externalPlaceId>606001882</externalPlaceId>
          <placeId>444444</placeId>
        </place>
      </places>
      <redemptionCode>22</redemptionCode>
      <redemptionType>PRINT</redemptionType>
      <redemptionUrl>http://www.fakeurl.com</redemptionUrl>
      <response>
        <code>SUCCESS</code>
        <field>
        </field>
        <message>Success</message>
      </response>
      <startDate>20111028</startDate>
      <termsAndConditions>terms and conditions test</termsAndConditions>
      <title>Make it so</title>
      <type>PERCENT_OFF</type>
    </offer>
  </offers>
</results>

 

Offer Mutate Endpoint

The offer/mutate endpoint uses five operators to provide the following operations on campaigns:

  • The ADD operator creates an Offer and relates it to the designated set of Places.
  • The SET operator updates the details of the Offer itself
  • The ADDPLACES operator allows the user to add additional Places to an existing offer.
  • The REMOVEPLACES operator allows the user to remove Places from an existing offer.
  • The REMOVE operator changes the status of an Offer to 'disabled' and sets it as hidden.

These operations are invoked via HTTPS POST to:

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

Request Parameters

Field

Type

Description

Operations

Array of Offer Operations

List of unique operations. 

Offer Operations

Every offer mutate request requires a list of Offer Operations, each with the following required fields:

Parameter

Description

Required

Type

Default Values

Examples

Notes

Operator

Defines the action for the Offer

 Yes

String

 N/A

  • ADD
  • SET
  • REMOVE
  • ADDPLACES
  • REMOVEPLACES

 Cannot be Null

Operand

Defines the Offer and details to operate on

 Yes

Offer

 N/A

 

 Cannot be Null

Offer

Field 

Description 

Required 

Type 

Limit

Default Values 

Examples 

Notes 

offerId

The ID of the Offer.

Required for all operations except ADD operation

Long value

 

N/A

 

Must be null in ADD operation.

places

A list of places associated with an offer.

Required for ADD, ADDPLACES and REMOVEPLACES operations

Not valid for SET or REMOVE operations

List of places (see Place type description below)

 

N/A

[{"externalPlaceId":"125_extShops"},{"externalPlaceId":"203_extShops"}]

 

 

See Place type description below for further info.

accountId

The id of the account which owns or will own the offer.

See Notes

Long value

 

N/A

 

An accountId is required only when the authenticated user is an internal CGM user in order to set the account context for the operation. If the logged in user is an external user (i.e. not an internal CGM employee) the accountId should not be specified.

title

The title of the Offer.

For ADD

String 

100 chars

N/A

 

 

description

The description of the Offer.

For ADD

String

500 chars

N/A

 

This should contain the details of the offer

offerStatus

The status of the Offer.

No

One of the following strings:

ACTIVE, DISABLE

 

ACTIVE

 

 

termsAndConditions

The terms and conditions of the Offer.

For ADD

String

200 chars

N/A

 

 

type

The type of the Offer.

For ADD

One of the following strings:

PERCENT_OFF, FREE, DOLLARS_OFF, GIFT_WITH_PURCHASE, BUY_ONE_GET_ONE_FREE, PURCHASE_WITH_PURCHASE, OTHER

 

N/A

 

Values supported: PERCENT_OFF, FREE, DOLLARS_OFF, GIFT_WITH_PURCHASE, BUY_ONE_GET_ONE_FREE, PURCHASE_WITH_PURCHASE, OTHER

redemptionType

The redemption type of the Offer.

For ADD

One of the following strings:
PRINT, ONLINE, BOTH

 

N/A

 

If ONLINE or BOTH is specified, a redemptionUrl is required.

redemptionCode

The redemption code of the Offer.

No

String

40 chars

N/A

 

 

redemptionUrl

The redemption url of the Offer.

Required for ADD when redemptionType = ONLINE or BOTH

String

500 chars

N/A

Must be a valid URL format beginning with "http://"  or "https://"

The URL that will be targeted via link from offer page.  For offers with redemptionType of ONLINE or BOTH

imageUrl DEPRECATED

The url of the image contained in the offer coupon/page

No

String

2000 chars

N/A

 

Formats supported: jpeg, png. Note: this field is not distributed

imageName DEPRECATED

The name of the image

No

String

60 chars

Will be set to the same value as offerName if imageName is not specified.

 

If it's null, the name of the image will be the title of the offer. Note: this field is not distributed

startDate

The start date of the Offer.

For ADD

String in format: yyyyMMdd

 

N/A

 

Format: yyyyMMdd

expirationDate

The expiration date of the Offer.

No

String in format: yyyyMMdd

 

N/A

 

Format: yyyyMMdd

Date cannot be before startDate

cyb

flag that specifies if we want to set the offer as CYB content provider

 

boolean

 

Defaults to true for CGM users when ADD operation is used to add the first offer to a place.  Is not a valid request or response parameter for external users.

 

Only for cap provider CGM. We can set offers as cyb and will make the previous cyb offer turn into CGM content provider.

Places

Offers may be associated to any number of places that are within any of a customer's active campaigns.  The properties of a place object in an ad group in a request as as follows.  Note that The places object array is not valid for the SET and REMOVE operations.  The ADD, ADDPLACES and REMOVEPLACES operations manage places associated to an offer).

PropertyTypeDescriptionRequiredNotes
externalPlaceIdStringThis is the user specific ID for referencing places in the CGM system.Required only if placeId is not specified. It is strongly recommended to always use externalPlaceId because the placeId is an internal CGM record locator and subject to change (the externalPlaceId will not change).
placeIdIntegerThe internal CGM record locator.|Required only if externalPlaceId is not specifiedIf both externalPlaceId and placeId are specified in  a request, the externalPlaceId will take precedence of placeId, as the placeId is subject to change.

 

Notes about the CYB (Claim Your Business) flag:

The cyb flag is used only for customers who advertiser directly with CityGrid Media.  This flag is used to designate a single listing offer as the primary/cyb offer.  This offer is special in that it will be published even when the associated listing does not have any active budget.  The first CGM offer created for a listing will be assigned the cyb=true flag by default.   If any subsequent offers are added to the listing, they are created as cyb=false unless explicitly indicated as cyb=true.   When an additional offer is added or set as cyb=true, the existing cyb offer gets marked as non-cyb, so that there is always only one cyb offer per listing.  If any offers operation is attempted by a GCM customer that would result in a listing having either zero or more than one cyb offer, an error will be returned in the API response.

  • The information in these bullet points applies only to customers whose campaigns are enrolled under the CGM (CityGrid Media) cap provider. 
  • When adding an offer, if it's the first offer for the listings specified and the cyb flag is not specified, cyb will default to true.
  • When adding an offer, if the related listings already have one cyb offer and the cyb flag is not specified, the new offer will be created as non-cyb by default.
  • When adding an offer, if it's not the first offer on a given place and cyb=true, any existing cyb offers on those places will become non-cyb.
  • Setting cyb to true on a non cyb offer will make existing cyb offers become non-cyb
  • Setting cyb to false on a cyb offer is not allowed. An error will be returned as this will result in no offers being the default cyb offer for a given place.
  • Removing a cyb offer is only allowed when it is the only offer left for the listing. Otherwise an error will be returned
  • Removing a non cyb offer is allowed at all times.

Mutate Offer Response Parameters

Properties

Field

Type

Description

rval

OfferResponsePage

List of Offers identified by the selector

OfferResponsePage

Field 

Description 

Type 

entries

List of OfferResponses

List

OfferResponse

Field 

Description 

Type 

places

List of places associated to the Offer

Array of place objects (see Places grid above for details)

offerId

The id of the offer

long

title

The text/title of the offer

String

description

The description of the offer

String

offerStatus

The status of the offer

ACTIVE|DISABLE

termsAndConditions

Terms and conditions associated to the offer

String

type

The type of the Offer

BUY_ONE_GET_ONE_FREE|DOLLARS_OFF|FREE|GIFT_WITH_PURCHASE|
OTHER|PERCENT_OFF|PURCHASE_WITH_PURCHASE

redemptionType

The redemption type of the offer

BOTH|ONLINE|PRINT

redemptionCode

The code of the redemption

String

redemptionUrl

The url of the redemption

String (in valid URL format)

imageUrl

The url of the image associated to the offer

String (in valid URL format)

imageNameA name related to the offer imageString

startDate

The start date of the offer

String (yyyyMMdd)

expirationDate

The expiration date of the offer

String (yyyyMMdd)

imageName

The name of the image associated to the offer

String

responseStatus

Response status

ResponseStatus 

ResponseStatus

Field

Type

Description

message

String

Error message

code

String

Error code

field

String

Field involved in the error (if applies)

Examples

The next section shows examples of Json ans XML requests.

Mutate operation (ADD) JSON request example.
Mutate operation (SET) JSON request example.
Mutate operation (REMOVE) JSON request example.
Mutate operation JSON response example. The response is the same for all operations.
Mutate operation (ADD) XML request example.
Mutate operation (SET) XML request example.
Mutate operation (REMOVE) XML request example.
Mutate operation XML response example. The response is the same for ADD, SET and REMOVE operations.

ADDPLACES and REMOVEPLACES Operations

The ADDPLACES and REMOVEPLACES operations allow a user to manage the set of listings associated to an existing offer.  A single offer may be related to multiple places (see places description above) and any place can have multiple offers, so these operations allow a user to add and remove individual listing offers without having to manage the whole set of associated places at once.  When the ADDPLACES or REMOVEPLACES operations are indicated, all other request parameters will be ignored as the only function of these operations is to manage the set of places associated to an offer. 

 

ADDPLACES and REMOVEPLACES example.

 

 

Error Handling

Each operation within a request has its own responseStatus to show success/error status for each operation.  However, if there is an issue with the format of the overall request, the response may contain only a single operation response since the request may not be parse-able.  In this case the HTTP status code will show error status as well (i.e. HTTP Status Code = 400 Bad Request)

Example of individual operation failure:

Example of total request failure

 

 

  • No labels