/
Offer API

CityGrid Advertising APIs

Offer API

Jul 18, 2013

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:

https://api.citygrid.com/advertising/offer/v3/get 

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)

Long

—

304998

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

    -H 'developerToken:myDevToken' \

    'https://api.citygrid.com/advertising/offer/v3/get?offerIds=122445872,121044952'

 

Example 2: Get the second page of five offers from all of the offers related to externalPlaceId=666666

 

curl -X GET \

    -H 'Accept:application/json' \

    -H 'authToken:mytoken' \

    -H 'developerToken:myDevToken' \

    'https://api.citygrid.com/advertising/offer/v3/get?externalPlaceIds=666666&numberResults=5&startIndex=1' 

 

Example 4: Get offers 122445872 and 121044952 in addition to ones related to externalPlaceId=666666

 

curl -X GET \

    -H 'Accept:application/json' \

    -H 'authToken:mytoken' \

    -H 'developerToken:myDevToken' \

    'https://api.citygrid.com/advertising/offer/v3/get?offerIds=122445872,121044952&externalPlaceIds=666666&numberResults=20'

 

Get Offer Response Properties

Field 

Description 

Type 

response

The structure and metadata for the entire response

(See complete response descriptions)

totalNumEntries

Integer

Total number of offers that match the criteria of the GET request across all pages

offers

Offer list

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

imageName

A name related to the offer image

String

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

      "imageUrl": "http://images.citysearch.net/assets/imgdb/image_ws/2011/10/27/0/BPYAbvWF1.jpeg",

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

      "imageUrl": "http://images.citysearch.net/assets/imgdb/image_ws/2011/10/27/0/KHJH098KLlkh.jpeg",

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

      <imageUrl>http://images.citysearch.net/assets/imgdb/image_ws/2011/10/27/0/BPYAbvWF1.jpeg</imageUrl>

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