Campaign Status API

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.

Endpoint

The operation is invoked via HTTPS GET to:

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

Request Parameters

Parameter	Description	Required	Type	Default	Example

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

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

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>

Campaign Status API

Introduction

Contents

Endpoint

Request Parameters

Request Header Values

Request Examples

Example 1: Get the pending campaign and/or adgroup explanation(s) for all campaign owned by the authToken.

Example 2: Get the pending campaign/adgroup explanation for two campaigns

Response Properties

Response Examples

Success Response

JSON

XML

Error Response

JSON

XML