The CityGrid AdGroup API is part of the Advertising API suite and enables developers to manage ad groups within a campaign. An ad group contains a collection of ads for a particular place, together with category and geographical targeting information. The API allows you to get and set data about the group. To manipulate the ads and targeting information within an ad group, see the AdGroupAd API, the AdGroupCriterion API, and the AdGroupGeo API.
The AdGroup API provides two endpoints: adgroup/get
and adgroup/mutate
.
Contents
The adgroup/get
endpoint retrieves information about one or more selected ad groups. The operation is invoked via HTTPS GET to:
|
Input data such as request parameters are subject to field size limits.
Parameter | Description | Required | Type | Default | Example |
---|---|---|---|---|---|
| Specified to retrieve ad groups by ID | Only if | Long list (Comma-delimited) | N/A | 4556,45,3344 |
| Specified to retrieve ad groups by place using the place's external ID | No | String | N/A | compexu3821 |
| Specified to retrieve ad groups by place | Only if | Long | N/A | 442442 |
| Specified to retrieve ad groups in a campaign | Only if | Long | N/A | 144534 |
| Page number of results to return (zero-based) | No | Integer | 0 | 5 |
| Number of results per page | No | Integer | 10 | 25 |
Header | Description | Required | Valid Values |
---|---|---|---|
| Requested format for the response | Yes |
|
| Authentication Token from the Authentication API | Yes | Valid token |
| The token you received at registration | Yes | Valid Token |
curl -X GET \ -H 'Accept:application/json' \ -H 'authToken:mytoken' \ -H 'developerToken:mydevtoken' \ 'https://api.citygrid.com/advertising/adgroup/v2/get?campaignId=16631&numberResults=3' |
curl -X GET \ -H 'Accept:application/xml' \ -H 'authToken:mytoken' \ -H 'developerToken:mydevtoken' \ 'https://api.citygrid.com/advertising/adgroup/v2/get?adGroupIds=6,11,155' |
curl -X GET \ -H 'Accept:application/json' \ -H 'authToken:mytoken' \ -H 'developerToken:mydevtoken' \ 'https://api.citygrid.com/advertising/adgroup/v2/get?campaignId=16631&externalPlaceId=aa-123' |
Property | Type | Description |
---|---|---|
| Response Metadata | |
| Integer | Number of ad groups returned |
| AdGroup list | Container for multiple ad groups |
| AdGroup | Details on a single ad group |
| Long | ID of the ad group |
externalPlaceId | String | External ID of the place associated with the ad group |
| Long | ID of the place associated with the ad group |
| Long | ID of the campaign that this ad group belongs to |
| String | Business ring-to number. This field is populated only when there is no metered phone line provisioned by CGM, but |
| String | The phone number that CGM provisioned a metered line for: either the existing metered line already provided by the advertising partner, or, if the advertising partner has not provisioned its own metered line, the business ring-to number. This field is populated only when a metered phone line is provisioned by CGM. |
| String | The displayPhone provided in the request or the metered line number if a line has been provisioned by CGM. |
| {LOCAL, TOLLFREE} | Metered phone number type |
| {true, false} | Whether calls may be recorded. |
| {0, 1, 2} | Status of the metered line: 0 = no or inactive metered line, 1 = has metered line, 2 = pending |
| String | Arbitrary name of the ad group |
| {Active, Inactive, Pending, Cancelled, Paused} | Status |
| Bid list | List of bids |
| Double | PPE (Price per Event) of the action of the bid |
| String | Action of the bid |
| String | Business email |
{ "totalNumEntries":1, "adGroups":[ { "id":5482, "externalPlaceId":aa-123, "campaignId":1234, "businessPhone":"", "providerPhone":"(617)523-5959", "displayPhone":"(617)892-4337", "meteredPhoneType":"LOCAL", "recordCalls":"false", "meteredLineStatus":1, "email":"massiminosboston@gmail.com", "name":"", "status":"Active", "bids":[ { "actionTargetName":"partner menu link", "ppe":0.55 }, { "actionTargetName":"partner reservation link", "ppe":0.55 }, { "actionTargetName":"send to phone (press send)", "ppe":0.55 }, { "actionTargetName":"customer menu link", "ppe":0.55 }, { "actionTargetName":"get directions", "ppe":0.55 }, { "actionTargetName":"featured sponsor ad views", "ppe":0.055 }, { "actionTargetName":"enhanced merchant profile", "ppe":0.55 }, { "actionTargetName":"virtual tour", "ppe":0.55 }, { "actionTargetName":"request quote", "ppe":0.55 }, { "actionTargetName":"profile api", "ppe":0.55 } ], "response":{ "field":"", "message":"Success", "code":"SUCCESS" }, } ] } |
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <results> <totalNumEntries>1</totalNumEntries> <adgroups> <adGroup> <id>5482</id> <placeId>4726033</placeId> <campaignId>1234</campaignId> <businessPhone></businessPhone> <providerPhone>(617)523-5959</providerPhone> <displayPhone>(617)892-4337</displayPhone> <meteredPhoneType>LOCAL</meteredPhoneType> <recordCalls>false</recordCalls> <meteredLineStatus>1</meteredLineStatus> <email>massiminosboston@gmail.com</email> <name/> <status>Active</status> <bids> <bid> <actionTargetName>partner menu link</actionTargetName> <ppe>0.55</ppe> </bid> <bid> <actionTargetName>partner reservation link</actionTargetName> <ppe>0.55</ppe> </bid> <bid> <actionTargetName>print driving directions</actionTargetName> <ppe>0.55</ppe> </bid> <bid> <actionTargetName>map & directions</actionTargetName> <ppe>0.55</ppe> </bid> <bid> <actionTargetName>consumer reviews views</actionTargetName> <ppe>0.55</ppe> </bid> <bid> <actionTargetName>recommend this business</actionTargetName> <ppe>0.55</ppe> </bid> <bid> <actionTargetName>save</actionTargetName> <ppe>0.55</ppe> </bid> <bid> <actionTargetName>print map</actionTargetName> <ppe>0.55</ppe> </bid> <bid> <actionTargetName>print offer</actionTargetName> <ppe>0.55</ppe> </bid> <bid> <actionTargetName>print profile</actionTargetName> <ppe>0.55</ppe> </bid> <bid> <actionTargetName>send to friend (email)</actionTargetName> <ppe>0.55</ppe> </bid> <bid> <actionTargetName>customer website link</actionTargetName> <ppe>0.55</ppe> </bid> <bid> <actionTargetName>email business form</actionTargetName> <ppe>0.55</ppe> </bid> <bid> <actionTargetName>trackable phone number</actionTargetName> <ppe>0.55</ppe> </bid> </bids> <response> <field/> <code>SUCCESS</code> <message>Success</message> </response> </adGroup> </adGroups> </result> |
A request with the parameter adGroupIds
misspelled as ids
will produce a result such as:
{ "totalNumEntries":0, "adGroups":[ { "id":"", "placeId":"", "campaignId":"", "businessPhone":"", "providerPhone":"", "displayPhone":"", "meteredPhoneType":"", "recordCalls":"", "meteredLineStatus":"", "email":"", "name":"", "status":"", "bids":[ ], "response":{ "field":"adGroupIds, campaignId or placeId", "message":"One of the parameters adGroupIds, campaignId or placeId is required", "code":"PARAMETER_REQUIRED" } } ] } |
A request to api.citygrid.com/advertising/adgroup/v2/get?adGroupIds=234,4A
produces a response such as:
<results> <totalNumEntries>0</totalNumEntries> <adGroups> <adGroup> <id></id> <placeId></placeId> <campaignId></campaignId> <businessPhone></businessPhone> <providerPhone></providerPhone> <displayPhone></displayPhone> <meteredPhoneType></meteredPhoneType> <recordCalls></recordCalls> <meteredLineStatus></meteredLineStatus> <email></email> <name></name> <status></status> <bids /> <response> <code>PARAMETER_FORMAT</code> <field>adGroupIds</field> <message>The parameter adGroupIds is formatted incorrectly. Valid format is comma-delimited number list.</message> </response> </adGroup> </adGroups> </results> |
The adgroup
/mutate
endpoint uses five operators to provide the following operations:
Please note that when the operation is REMOVE, the ad group is not physically removed from the system. |
These operations are invoked via HTTPS POST to:
|
Every adgroup/mutate
request requires the following two parameters:
Property | Type | Description | Required |
---|---|---|---|
| {ADD, REMOVE, SET, PAUSE, UNPAUSE} | Type of operation to perform (case sensitive). See the section below for information regarding the PAUSE and UNPAUSE operations | Yes |
| Ad Group | The ad group to operate on | Yes |
The properties of an ad group object in a request are:
Property | Description | Type | Required | Limit |
---|---|---|---|---|
| The ID of the ad group | Long | If operator is SET or REMOVE | 10 digits |
| External ID of the place | String | If operator is ADD | 256 chars |
| ID of the Place | Long | If operator is ADD | 10 digits |
| ID of the campaign containing the ad group | Long | If operator is ADD | 10 digits |
| The duration in months of the contract | Integer | No. 0 es a valid value for SET operator | |
| The monthly fee associated with the ad group | Double | No. 0 is a valid value for SET operator | |
| Bid list | Bid | If operator is ADD | see below |
| Budget object for this request | Budget | No- See details below | see below |
businessPhone | The number to be displayed on place pages in the CityGrid network | String | No | see below |
| The number to be displayed on place pages in the CityGrid network | String | No | see below |
| Metered phone number type | {LOCAL, TOLLFREE} | No | |
| Whether call recording is set on the metered line | {0, 1} | No | |
| The primary email for this business | String | No | 60 chars |
| How a metered line is provisioned. 0=Provision a metered line. 1=Do NOT provision a metered line. | {0, 1} | No. If not specified, a metered line will be provisioned (default = 0). |
Bids
The properties of a bid object in an ad group in a request are:
Property | Description | Required | Type | Default | Example | Limit |
---|---|---|---|---|---|---|
ppe | The PPE (Price per Event) of the action of the bid | Yes | Double | N/A | 1.30 | 7 digits for integer part, 4 decimals |
actionTargetName | The action of the bid | Yes | String | N/A | listing_profile | 40 chars |
Advertisers should set up a bid amount for each of the following action targets:
For virtual places, the only available action target is:
The AdGroup operand may or may not include a budget object. If you wish to set budget at the Campaign level do not include the budget object in your AdGroup API requests. You may create an AdGroup budget at the time the AdGroup is created (ADD operation) or you may add it later using the AdGroup SET operation. Once the budget is added at the AdGroup level, it cannot be configured at the Campaign level and vice versa. The properties of a budget object in a request are as follows:
Property | Type | Description | Required | Notes |
---|---|---|---|---|
| Double | Amount of budget in U.S. Dollars | Yes | Max 7 digits for integer part, 4 decimals |
period | Daily/ | Period over which to spend the budget | No | If this property is not supplied, the budget period is defaulted to monthly |
Notes:
businessPhone
and displayPhone
will remove the values from the ad group.businessPhone
and displayPhone
, the GET operation will return an empty string for meteredPhoneType
and recordCalls
, and 0 for meteredLineStatus
. Furthermore, updates to meteredPhoneType
and recordCalls
will not be allowed unless businessPhone
and displayPhone
are added or are nonempty in the same request.businessPhone
or displayPhone
field will produce an error with response code PARAMETER_ASSOCIATION_ACTION_NOT_PERFORMED.businessPhone
is present, the phone number associated with the place will be used as the business phone.assignMeteredLine
fieldemail
field will remove the value from the ad group.contractTermMonths
monthlyServiceFee
meteredPhoneType
recordCalls
assignMeteredLine
bids
field will produce an error with response code INVALID_REQUEST_BODY.(312)456-7890
3214567890
312-456-7890
+1 (215)456-7890
ppe
field will produce an error with response code PARAMETER_INVALID.budget.amount or budget.
period results in a PARAMETER_INVALID error.
businessPhone
displayPhone
meteredPhoneType
recordCalls
assignMeteredLine
businessPhone
is not passed in, then the current ring-to number is used for the business phone. If the displayPhone
is not passed in, then the current provisioned number used for the display phone.businessPhone
parameter is not passed in, the place's phone number is used for the business phone. If the displayPhone
parameter is not passed in, the current ring-to number is used for the display phone.Header | Description | Required | Valid Values |
---|---|---|---|
| Media type of the request body | Yes |
|
| Requested format for the response | Yes |
|
| Authentication token from the Authentication API | Yes | Valid token |
| The token you received at registration | Yes | Valid Token |
{ "mutateOperationListResource":[ { "operator":"ADD", "operand":{ "placeId":"123456", "externalPlaceId":"number123456", "campaignId":"1351", "contractTermMonths":"12", "monthlyServiceFee":"4000", "businessPhone":"(925)722-1234", "displayPhone":"(215)722-1759", "meteredPhoneType":"LOCAL", "recordCalls":"1", "assignMeteredLine":"1", "email":"valid.example@somewhere.com", "bids":[ { "actionTargetName":"print profile", "ppe":"1.82" }, { "actionTargetName":"customer menu link", "ppe":"0.42" }, { "actionTargetName":"send to phone (press send)", "ppe":"0.12" } ] } } ] } |
{ "mutateOperationListResource":[ { "operator":"SET", "operand":{ "adGroupId":"5482", "contractTermMonths":"12", "monthlyServiceFee":"4000", "businessPhone":"(925)722-1234", "displayPhone":"(215)722-1759", "meteredPhoneType":"LOCAL", "recordCalls":"1", "assignMeteredLine":"1", "email":"valid.example@somewhere.com", "bids":[ { "actionTargetName":"print profile", "ppe":"1.82" }, { "actionTargetName":"customer menu link", "ppe":"0.42" }, { "actionTargetName":"send to phone (press send)", "ppe":"0.12" } ] } } ] } |
Property | Type | Description |
---|---|---|
| Response Metadata | |
| Integer | Number of ad groups affected by mutate |
| AdGroup list | ad group(s) affected by the mutate |
| Long | The id of the ad group |
| Long | The ID of the place this ad group is assigned to |
| String | External ID of the place this ad group is assigned to |
| Long | The ID of the campaign this ad group is part of |
| Long | The ID of the product associated to the ad group |
| Integer | The duration in months of the contract |
| Double | The monthly fee associated to the ad group in U.S. Dollars |
| String | The name of the ad group (currently blank) |
| {Active, Inactive, Pending, Cancelled, Paused} | The status of the ad group |
| String | same as request |
| String | same as request |
providerPhone | String | The phone number that CGM provisioned a metered line for: either the existing metered line already provided by the advertising partner, or, if the advertising partner has not provisioned its own metered line, the business ring-to number. This field is populated only when a metered phone line is provisioned by CGM. |
| {0, 1} | same as request |
| {0, 1} | same as request |
| {LOCAL, TOLLFREE} | Metered line type, same as request |
| {0, 1, 2} | metered line status 0=Inactive, 1=active, 2=pending |
| String | Business email |
| Bid list | Bids applied to this ad group |
| Double | The PPE (Price per Event) of the action of the bid |
| String | The action of the bid |
{ "adGroups":[ { "id":"641", "placeId":"0", "campaignId":"1351", "productId":"125", "contractTermMonths":"12", "monthlyServiceFee":"0.0", "businessPhone":"(925)722-6839", "displayPhone":"", "meteredPhoneType":"LOCAL", "recordCalls":"false", "email":"valid.example@somewhere.com", "assignMeteredLine":"", "name":"", "status":"Active", "response":{ "field":"", "message":"Success", "code":"SUCCESS" }, "bids":[ { "actionTargetName":"print profile", "ppe":"1.82" }, { "actionTargetName":"customer menu link", "ppe":"0.42" }, { "actionTargetName":"send to phone (press send)", "ppe":"0.12" } ] } ] } |
<results> <adGroups> <adGroup> <id>645</id> <placeId>0</placeId> <campaignId>1351</campaignId> <productId>125</productId> <contractTermMonths>12</contractTermMonths> <monthlyServiceFee>0.0</monthlyServiceFee> <businessPhone>(925)722-6111</businessPhone> <displayPhone></displayPhone> <meteredPhoneType>LOCAL</meteredPhoneType> <recordCalls>false</recordCalls> <email>your.email@somedomain.com</email> <assignMeteredLine></assignMeteredLine> <bids> <bid> <actionTargetName>print profile</actionTargetName> <ppe>1.82</ppe> </bid> <bid> <actionTargetName>customer menu link</actionTargetName> <ppe>0.42</ppe> </bid> <bid> <actionTargetName>send to phone (press send)</actionTargetName> <ppe>0.12</ppe> </bid> </bids> <name></name> <status>Active</status> <response> <field/> <code>SUCCESS</code> <message>Success</message> </response> </adGroup> </adGroups> </results> |
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <results> <adGroups> <adGroup> <id/> <placeId>123456</placeId> <campaignId>1351</campaignId> <productId/> <contractTermMonths>12</contractTermMonths> <monthlyServiceFee>4000</monthlyServiceFee> <businessPhone>(925)722-1234</businessPhone> <displayPhone>(215)722-1759</displayPhone> <meteredPhoneType>LOCAL</meteredPhoneType> <recordCalls>false</recordCalls> <email>valid.example@somewhere.com</email> <assignMeteredLine>1</assignMeteredLine> <bids> <bid> <actionTargetName>print profile</actionTargetName> <ppe>1.82</ppe> </bid> <bid> <actionTargetName>customer menu link</actionTargetName> <ppe>0.42</ppe> </bid> <bid> <actionTargetName>send to phone (press send)</actionTargetName> <ppe>0.12</ppe> </bid> </bids> <name/> <status/> <response> <field/> <code>ENTITY_STATE_INVALID</code> <message>The request could not be processed because a change request is still in pending.</message> </response> </adGroup> </adGroups> </results> |
{ "adGroups":[ { "id":"", "placeId":"123456", "campaignId":"1351", "productId":"", "contractTermMonths":"12", "monthlyServiceFee":"", "businessPhone":"", "displayPhone":"(215)722-1759", "meteredPhoneType":"local", "recordCalls":"", "email":"valid.example@somewhere.com", "assignMeteredLine":"", "bids":[ { "actionTargetName":"print profile", "ppe":"1.82" }, { "actionTargetName":"customer menu link", "ppe":"0.42" }, { "actionTargetName":"send to phone (press send)", "ppe":"0.12" } ], "name":"", "status":"", "response":{ "field":"", "message":"The request could not be processed because a change request is still in pending.", "code":"ENTITY_STATE_INVALID" } } ] } |
displayPhone
field{ "adGroups":[ { "id":"8482992", "placeId":"", "campaignId":"", "productId":"", "contractTermMonths":"", "monthlyServiceFee":"", "displayPhone":"", "businessPhone":"(215)722-1759", "meteredPhoneType":"", "recordCalls":"", "email":"", "assignMeteredLine":"1", "bids":[ ], "name":"", "status":"", "responseStatus":{ "code":"PARAMETER_ASSOCIATION_ACTION_NOT_PERFORMED", "message":"The parameter business phone has an association with display phone. All associated fields need to be updated/deleted also.", "field":"business phone" } } ] } |
The PAUSE and UNPAUSE operations allow a user to pause Ad/Budget distribution for a specific AdGroup within a campaign and subsequently reactivate (unpause) the Ads/Budget at a later time. When the PAUSE or UNPAUSE operations are indicated all other request parameters will be ignored as the only function of these operations is to change the campaign's servingStatus between ACTIVE and PAUSED. Note that the user can only PAUSE an ACTIVE ad group (i.e. cannot pause campaigns that are PENDING, CANCELED, etc) and can only UNPAUSE a PAUSED ad group.
Note that when an ad group is set to PAUSE or UNPAUSE, the status will take affect immediately. |
{"mutateOperationListResource": [{ "operator": "PAUSE","operand": {"adGroupId":"8167"} }]} |
{ "adGroups": [ { "id": "8167", "placeId": "40862360", "externalPlaceId": "40862360", "campaignId": "900", "productId": "6", "contractTermMonths": "0", "monthlyServiceFee": "9.95", "businessPhone": "", "providerPhone": "", "displayPhone": "", "meteredPhoneType": "", "recordCalls": "", "email": "", "assignMeteredLine": "", "meteredLineStatus": "", "bids": [ { "actionTargetName": "enhanced merchant profile", "ppe": "1.75" } ], "name": "", "period": "", "budgetAmount": "", "status": "Paused", "cancelDate": "", "responseStatus": { "code": "SUCCESS", "message": "Success", "field": "" } } ] } |
{"mutateOperationListResource": [{ "operator": "UNPAUSE","operand": {"adGroupId":"8167"} }]} |
{ "adGroups": [ { "id": "8167", "placeId": "40862360", "externalPlaceId": "40862360", "campaignId": "900", "productId": "6", "contractTermMonths": "0", "monthlyServiceFee": "9.95", "businessPhone": "", "providerPhone": "", "displayPhone": "", "meteredPhoneType": "", "recordCalls": "", "email": "", "assignMeteredLine": "", "meteredLineStatus": "", "bids": [ { "actionTargetName": "enhanced merchant profile", "ppe": "1.75" } ], "name": "", "period": "", "budgetAmount": "", "status": "Active", "cancelDate": "", "responseStatus": { "code": "SUCCESS", "message": "Success", "field": "" } } ] } |