/
Campaign Status API

CityGrid Advertising APIs

Campaign Status API

Feb 04, 2013

Introduction

The CityGrid Campaign/Adgroup Status API is part of the Advertising API suite and generates a list of reasons why a campaign and/or adgroup is not active. Report information is available in both JSON or XML.

Contents

Endpoint

The operation is invoked via HTTPS GET to:

api.citygrid.com/advertising/campaign/v2/status

Request Parameters

Parameter

Description

Required

Type

Default

Example

campaignId

Comma-separated list of campaign IDs. If specified, externalCampaignId must be left empty.

No

Long

 

4352,8473,242

externalCampaignId

Comma-separated list of external IDs of the campaign. If specified, campaignId must be left empty.

No

Long

 

1,2,3,4

Request Header Values

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 the pending campaign and/or adgroup explanation(s) for all campaign owned by the authToken.
curl -X GET \
     -H 'Accept:application/json' \
     -H 'authToken:mytoken' \
    'https://api.citygrid.com/advertising/campaign/v2/status'
Example 2: Get the pending campaign/adgroup explanation for two campaigns
curl -X GET \
     -H 'Accept:application/json' \
     -H 'authToken:mytoken' \
    'https://api.citygrid.com/advertising/campaign/v2/status?campaignId=3229772,2719172'

Response Properties

Property

Type

Description

response

Response Metadata

(See complete response descriptions)

totalNumEntries

Integer

Total number of campaigns in the response.

campaignId

String

The campaign ID.

externalCampaignId

String

External ID of the campaign.

campaignName

String

Arbitrary campaign name, not shown in the ads.

status

{ACTIVE, CANCELLED, PENDING}

Status of the campaign in the system:

Active: Campaign is serving ads

Cancelled: User cancelled the campaign

Pending: Campaign is not serving ads. See reasons for an explanation on why its not serving.

adGroupId

String

ID of the ad group.

reasons

String

The reason a campaign or adgroup is not active.

Response Examples

Success Response

The following shows success responses in JSON and XML format.

JSON
{
  "totalNumEntries": 2,
  "campaigns": [
    {
      "campaignId": "3303582",
      "externalCampaignId": "",
      "campaignName": "106233",
      "status": "Pending",
      "adGroups": [
        {
          "adGroupId": "43054742",
          "reasons": [
            "Unmatched Place Info"
          ]
        }
      ],
      "reasons": [

      ]
    },
    {
      "campaignId": "3334552",
      "externalCampaignId": "",
      "campaignName": "103336",
      "status": "PENDING",
      "adGroups": [

      ],
      "reasons": [
        "Campaign has no adgroups"
      ]
    }
  ],
  "response": {
    "code": "SUCCESS",
    "message": "Success",
    "field": ""
  }
}
XML
<results>
    <totalNumEntries>2</totalNumEntries>
    <campaigns>
        <campaign>
            <campaignId>3303582</campaignId>
            <externalCampaignId/>
            <campaignName>106233</campaignName>
            <status>Pending</status>
            <adgroups>
                <adgroup>
                    <adGroupId>43054742</adGroupId>
                    <reasons>
                        <reason>Unmatched Place Info</reason>
                    </reasons>
                </adgroup>
            </adgroups>
            <reasons/>
        </campaign>
        <campaign>
            <campaignId>3334552</campaignId>
            <externalCampaignId/>
            <campaignName>103336</campaignName>
            <status>PENDING</status>
            <adgroups/>
            <reasons>
                <reason>Campaign has no adgroups</reason>
            </reasons>
        </campaign>
    </campaigns>
    <response>
        <code>SUCCESS</code>
        <field/>
        <message>Success</message>
    </response>
</results>

Error Response

The following shows error responses (in JSON and XML format) when campaignId are not comma separated numbers.

JSON
{
  "totalNumEntries": 0,
  "campaigns": [

  ],
  "response": {
    "code": "PARAMETER_FORMAT",
    "message": "The parameter, campaignId, is formatted incorrectly. Valid formats are numbers separated by comma.",
    "field": "campaignId"
  }
}
XML
<results>
    <totalNumEntries>0</totalNumEntries>
    <campaigns/>
    <response>
        <code>PARAMETER_FORMAT</code>
        <field>campaignId</field>
        <message>The parameter, campaignId, is formatted incorrectly. Valid formats are numbers separated by comma.</message>
    </response>
</results>