AdGroupGeo API

Introduction

The CityGrid AdGroup Geo API is part of the Advertising API suite and allows users to add and remove geographic targeting to ad groups.

AdGroup Geography types are PRIMARY , SECONDARY, and CUSTOMER_SELECTED_GEOGRAPHY.

PRIMARY and SECONDARY are determined based on the listing address and will not be able to modified by AdGroup Geo API.

The CityGrid AdGroup Geo API is used only to add / remove CUSTOMER_SELECTED_GEOGRAPHY.

The AdGroupGeo API must be called to associate geography data with an ad group when the ad group's business does not have a physical location (i.e. when the related place has isVirtual=true). It does not need to be called when the business does possess a physical address, since geographic targeting is initially inferred from the business address.

AdGroupGeo Get Endpoint

The adgroupgeo/get endpoint retrieves information about adgroup-geography associations. The operation is invoked via HTTPS GET to:

api.citygrid.com/advertising/adgroupgeo/v2/get

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

Request Parameters

Parameter	Description	Required	Type	Default	Example
`adGroupId`	The ad group whose associated geographies are to be retrieved	Yes	Long	N/A
`startIndex`	Page number of results to return (zero-based)	No	Integer	0	5
`numberResults`	Number of results per page	No	Integer	10	25

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: Retrieve adgroup-geography associations for ad group 38

curl -X GET \
    -H 'Accept:application/json' \
    -H 'authToken:mytoken' \
    -H 'developerToken:myDevToken' \
    'https://api.citygrid.com/advertising/adgroupgeo/v2/get?adGroupId=38'

Example 2: Get the third page of results for ad group 38, three results per page, in XML

curl -X GET \
    -H 'Accept:application/xml' \
    -H 'authToken:mytoken' \
    -H 'developerToken:myDevToken' \
    'https://sandbox-api.citygrid.com/advertising/adgroupgeo/v2/get?adGroupId=38&startIndex=2&numberResults=3'

Response Properties

Property	Type	Description
`response`	Response Metadata	(See complete response descriptions)
`totalNumEntries`	Integer	Total number of results
`adGroupGeos`	AdGroupGeo list	List of results
`adGroupGeo`	AdGroupGeo	An adgroup-geography association
`adGroupId`	Long	The ID of the ad group
`adgroupGeoType`	{PRIMARY, SECONDARY, CUSTOMER_SELECTED_GEOGRAPHY}	The type of association
`geographyId`	Long	The ID of the geography
`geographyName`	String	The name of the geography
`geographyType`	String	The type of the geography

Response Examples

Example 1: A JSON success response

{
  "totalNumEntries":21,
  "adGroupGeos":[
    {
      "adGroupId":"1",
      "geographyId":"7340",
      "adGroupGeoType":"SECONDARY",
      "geographyName":"Chinatown",
      "geographyType":"NEIGHBORHOOD",
      "response":{
        "field":"",
        "message":"Success",
        "code":"SUCCESS"
      }
    },
    {
      "adGroupId":"1",
      "geographyId":"7344",
      "adGroupGeoType":"SECONDARY",
      "geographyName":"East Village",
      "geographyType":"NEIGHBORHOOD",
      "response":{
        "field":"",
        "message":"Success",
        "code":"SUCCESS"
      }
    },
    {
      "adGroupId":"1",
      "geographyId":"7370",
      "adGroupGeoType":"SECONDARY",
      "geographyName":"Greenwich Village",
      "geographyType":"NEIGHBORHOOD",
      "response":{
        "field":"",
        "message":"Success",
        "code":"SUCCESS"
      }
    },
    {
      "adGroupId":"1",
      "geographyId":"7399",
      "adGroupGeoType":"SECONDARY",
      "geographyName":"Little Italy",
      "geographyType":"NEIGHBORHOOD",
      "response":{
        "field":"",
        "message":"Success",
        "code":"SUCCESS"
      }
    },
    {
      "adGroupId":"1",
      "geographyId":"7400",
      "adGroupGeoType":"SECONDARY",
      "geographyName":"Lower East Side",
      "geographyType":"NEIGHBORHOOD",
      "response":{
        "field":"",
        "message":"Success",
        "code":"SUCCESS"
      }
    },
    {
      "adGroupId":"1",
      "geographyId":"7428",
      "adGroupGeoType":"SECONDARY",
      "geographyName":"NoHo",
      "geographyType":"NEIGHBORHOOD",
      "response":{
        "field":"",
        "message":"Success",
        "code":"SUCCESS"
      }
    },
    {
      "adGroupId":"1",
      "geographyId":"7429",
      "adGroupGeoType":"SECONDARY",
      "geographyName":"NoLita",
      "geographyType":"NEIGHBORHOOD",
      "response":{
        "field":"",
        "message":"Success",
        "code":"SUCCESS"
      }
    },
    {
      "adGroupId":"1",
      "geographyId":"7448",
      "adGroupGeoType":"PRIMARY",
      "geographyName":"SoHo",
      "geographyType":"NEIGHBORHOOD",
      "response":{
        "field":"",
        "message":"Success",
        "code":"SUCCESS"
      }
    },
    {
      "adGroupId":"1",
      "geographyId":"7452",
      "adGroupGeoType":"SECONDARY",
      "geographyName":"Tribeca",
      "geographyType":"NEIGHBORHOOD",
      "response":{
        "field":"",
        "message":"Success",
        "code":"SUCCESS"
      }
    },
    {
      "adGroupId":"1",
      "geographyId":"66450",
      "adGroupGeoType":""CUSTOMER_SELECTED_GEOGRAPHY",
      "geographyName":"Hudson",
      "geographyType":"NEIGHBORHOOD",
      "response":{
        "field":"",
        "message":"Success",
        "code":"SUCCESS"
      }
    }
  ]
}

Example 2: An XML success response

<results>
  <totalNumEntries>21</totalNumEntries>
  <adGroupGeos>
    <adGroupGeo>
      <adGroupId>1</adGroupId>
      <geographyId>7340</geographyId>
      <adGroupGeoType>SECONDARY</adGroupGeoType>
      <geographyName>Chinatown</geographyName>
      <geographyType>NEIGHBORHOOD</geographyType>
      <response>
        <field/>
        <message>Success</message>
        <code>SUCCESS</code>
      </response>
    </adGroupGeo>
    <adGroupGeo>
      <adGroupId>1</adGroupId>
      <geographyId>7344</geographyId>
      <adGroupGeoType>SECONDARY</adGroupGeoType>
      <geographyName>East Village</geographyName>
      <geographyType>NEIGHBORHOOD</geographyType>
      <response>
        <field/>
        <message>Success</message>
        <code>SUCCESS</code>
      </response>
    </adGroupGeo>
    <adGroupGeo>
      <adGroupId>1</adGroupId>
      <geographyId>7370</geographyId>
      <adGroupGeoType>SECONDARY</adGroupGeoType>
      <geographyName>Greenwich Village</geographyName>
      <geographyType>NEIGHBORHOOD</geographyType>
      <response>
        <field/>
        <message>Success</message>
        <code>SUCCESS</code>
      </response>
    </adGroupGeo>
    <adGroupGeo>
      <adGroupId>1</adGroupId>
      <geographyId>7399</geographyId>
      <adGroupGeoType>SECONDARY</adGroupGeoType>
      <geographyName>Little Italy</geographyName>
      <geographyType>NEIGHBORHOOD</geographyType>
      <response>
        <field/>
        <message>Success</message>
        <code>SUCCESS</code>
      </response>
    </adGroupGeo>
    <adGroupGeo>
      <adGroupId>1</adGroupId>
      <geographyId>7400</geographyId>
      <adGroupGeoType>SECONDARY</adGroupGeoType>
      <geographyName>Lower East Side</geographyName>
      <geographyType>NEIGHBORHOOD</geographyType>
      <response>
        <field/>
        <message>Success</message>
        <code>SUCCESS</code>
      </response>
    </adGroupGeo>
    <adGroupGeo>
      <adGroupId>1</adGroupId>
      <geographyId>7428</geographyId>
      <adGroupGeoType>SECONDARY</adGroupGeoType>
      <geographyName>NoHo</geographyName>
      <geographyType>NEIGHBORHOOD</geographyType>
      <response>
        <field/>
        <message>Success</message>
        <code>SUCCESS</code>
      </response>
    </adGroupGeo>
    <adGroupGeo>
      <adGroupId>1</adGroupId>
      <geographyId>7429</geographyId>
      <adGroupGeoType>SECONDARY</adGroupGeoType>
      <geographyName>NoLita</geographyName>
      <geographyType>NEIGHBORHOOD</geographyType>
      <response>
        <field/>
        <message>Success</message>
        <code>SUCCESS</code>
      </response>
    </adGroupGeo>
    <adGroupGeo>
      <adGroupId>1</adGroupId>
      <geographyId>7448</geographyId>
      <adGroupGeoType>PRIMARY</adGroupGeoType>
      <geographyName>SoHo</geographyName>
      <geographyType>NEIGHBORHOOD</geographyType>
      <response>
        <field/>
        <message>Success</message>
        <code>SUCCESS</code>
      </response>
    </adGroupGeo>
    <adGroupGeo>
      <adGroupId>1</adGroupId>
      <geographyId>7452</geographyId>
      <adGroupGeoType>SECONDARY</adGroupGeoType>
      <geographyName>Tribeca</geographyName>
      <geographyType>NEIGHBORHOOD</geographyType>
      <response>
        <field/>
        <message>Success</message>
        <code>SUCCESS</code>
      </response>
    </adGroupGeo>
    <adGroupGeo>
      <adGroupId>1</adGroupId>
      <geographyId>66450</geographyId>
      <adGroupGeoType>CUSTOMER_SELECTED_GEOGRAPHY</adGroupGeoType>
      <geographyName>Hudson</geographyName>
      <geographyType>NEIGHBORHOOD</geographyType>
      <response>
        <field/>
        <message>Success</message>
        <code>SUCCESS</code>
      </response>
    </adGroupGeo>
  </adGroupGeos>
</results>

Example 3: No authentication token (JSON)

{
  "field":"",
  "code":"AUTH_TOKEN_NONE",
  "message":"No Authentication Token supplied"
}

Example 4: Missing required parameter (XML)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<results>
  <totalNumEntries>1</totalNumEntries>
  <adGroupGeos>
    <adGroupGeo>
      <adGroupId></adGroupId>
      <geographyId></geographyId>
      <adGroupGeoType></adGroupGeoType>
      <geographyName></geographyName>
      <geographyType></geographyType>
      <response>
        <code>PARAMETER_REQUIRED</code>
        <field>adGroupId</field>
        <message>The parameter adGroupId is required but has not been supplied</message>
      </response>
    </adGroupGeo>
  </adGroupGeos>
</results>

AdGroupGeo Mutate Endpoint

The adgroupgeo/mutate endpoint allows adgroup-geography associations to be created and removed using the ADD and REMOVE operation keywords, respectively.

These operations are invoked via HTTPS POST to:

api.citygrid.com/advertising/adgroupgeo/v2/mutate

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

Request Parameters

Every adgroupgeo/mutate request requires the following two parameters:

Property	Type	Description	Required
`operator`	{ADD, REMOVE}	Type of operation to perform (case sensitive)	Yes
`operand`	AdGroupGeo(s)	The association(s) to operate on	Yes

The properties of an adgroupgeo object in a request are:

Field	Description	Required	Type
`adGroupId`	ID of the ad group	Yes	Long
`postalCodeTarget`	Contains postal code geography data	No	PostalCodeTarget
`cityTarget`	Contains city geography data	No	CityTarget
`metroTarget`	Contains metro Geography data	No	MetroTarget
`provinceTarget`	Contains province Geography data	No	ProvinceTarget
`neighborhood`	Contains neighborhood Geography data	No	Neighborhood

You may specify one and only one geography type (postalCodeTarget, cityTarget, metroTarget, provinceTarget, or neighborhood).

The properties of a cityTarget are:

Field	Description	Required	Type	Limit
`cityName`	Name of the city	Yes	String	128 chars
`provinceName`	State/Province of the city	Yes	String	40 chars

The properties of a postalCodeTarget are:

Field	Description	Required	Type	Limit
`postalCode`	5 digit US postal code	Yes	String	5 digits

The properties of a metroTarget are:

Field	Description	Required	Type	Limit
`metroName`	Name of the metro	Yes, if metro code is not defined	String	60 chars
`provinceName`	Province or state abbreviation. Example: New York state abbreviation is NY.	Yes	String	40 chars

The properties of a provinceTarget are:

Field	Description	Required	Type	Limit
`provinceName`	Province or state abbreviation. Example: New York state abbreviation is NY.	Yes, if the province code is not defined	String	40 chars

The properties of a neighborhood are:

Field	Description	Required	Type	Limit
`neighborhoodName`	Name of the neighborhood	Yes	String	80 chars
`provinceName`	Province or state abbreviation. Example: New York state abbreviation is NY.	Yes	String	40 chars

Request Header Values

Header	Description	Required	Valid Values
`Content-Type`	Media type of the request body, if any	Yes	`application/json` `application/xml`
`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: Add Hudson, NY to ad group 78

{
  "mutateOperationListResource":[
    {
      "operator": "ADD",
      "operand": {
        "adGroupId": "78",
        "cityTarget": {
          "cityName": "Hudson",
          "provinceName": "NY"
        }
      }
    }
  ]
}

Example 2: Remove Hudson, NY from ad group 78

{
  "mutateOperationListResource": [
    {
      "operator": "REMOVE",
      "operand": {
        "adGroupId": "78",
        "cityTarget" :{
          "cityName": "Hudson",
          "provinceName": "NY"
        }
      }
    }
  ]
}

Example 3: Add Postal Code 90048 to ad group 78

{
  "mutateOperationListResource":[
    {
      "operator": "ADD",
      "operand": {
        "adGroupId": "78",
        "postalCodeTarget": {
          "postalCode": "90048",
        }
      }
    }
  ]
}

Example 4: Remove Postal Code 90048 from ad group 78

{
  "mutateOperationListResource": [
    {
      "operator": "REMOVE",
      "operand": {
        "adGroupId": "78",
        "postalCodeTarget" :{
          "postalCode": "90048",
        }
      }
    }
  ]
}

Example 5: Add Vinings, GA to ad group 1055

<mutateOperationListResource>
<mutateOperation>
  <operator>ADD</operator>
  <operand>
    <adGroupId>1055</adGroupId>
    <cityTarget>
      <provinceName>GA</provinceName>
      <cityName>Vinings</cityName>
    </cityTarget>
  </operand>
</mutateOperation>
</mutateOperationListResource>

Example 6: Remove Vinings, GA from ad group 1055

<mutateOperationListResource>
<mutateOperation>
  <operator>REMOVE</operator>
  <operand>
    <adGroupId>1055</adGroupId>
    <cityTarget>
      <provinceName>GA</provinceName>
      <cityName>Vinings</cityName>
    </cityTarget>
  </operand>
</mutateOperation>
</mutateOperationListResource>

Example 7: Add Sulphur Springs, TX Metro to ad group 1207

{
  "mutateOperationListResource": [
    {
      "operator": "ADD",
      "operand": {
        "adGroupId": "1207",
        "metroTarget": {
          "metroName": "Sulphur Springs",
          "provinceName": "TX"
        }
      }
    }
  ]
}

Example 8: Remove neighborhood East Highland Village, CA from ad group 1001

<mutateOperationListResource>
  <mutateOperation>
    <operator>REMOVE</operator>
    <operand>
      <adGroupId>1001</adGroupId>
      <neighborhood>
        <provinceName>CA</provinceName>
        <neighborhoodName>East Highland Village</neighborhoodName>
      </neighborhood>
    </operand>
  </mutateOperation>
</mutateOperationListResource>

Example 9: Add California to ad group 78

{
  "mutateOperationListResource": [
    {
      "operator": "ADD",
      "operand": {
        "adGroupId": "78",
        "provinceTarget": {
          "provinceName": "CA"
        }
      }
    }
  ]
}

Response Properties

Property	Type	Description
`response`	Response Metadata	(See complete response descriptions)
`adGroupId`	Long	The ID of the ad group
`geographyId`	Long	The ID of the geography
`geographyName`	String	The name of the geography
`geographyType`	String	The type of the geography

Response Examples

All success responses are the same for ADD and REMOVE operations.

Example 1: JSON response for modified city target

{
  "adGroupGeos":[
    {
      "adGroupId": "78",
      "geographyId": "66450",
      "geographyType": "CITY",
      "geographyName": "Hudson",
      "response": {
        "field": "",
        "message": "Success",
        "code": "SUCCESS"
      }
    }
  ]
}

Example 2: XML response for modified city target

<results>
  <adGroupGeos>
    <adGroupGeo>
      <adGroupId>1055</adGroupId>
      <geographyId>129573<geographyId>
      <geographyType>CITY</geographyType>
      <geographyName>Vinings</geographyName>
      <response>
        <field/>
        <code>SUCCESS</code>
        <message>Success</message>
      </response>
    </adGroupGeo>
  </adGroupGeos>
</results>

Example 3: JSON response for modified postal code target

{
  "adGroupGeos":[
    {
      "adGroupId": "78",
      "geographyId": "22519",
      "geographyType": "POSTAL_CODE",
      "geographyName": "90048",
      "response": {
        "field": "",
        "message": "Success",
        "code": "SUCCESS"
      }
    }
  ]
}

Example 4: XML response for modified city target

<results>
  <adGroupGeos>
    <adGroupGeo>
      <adGroupId>1055</adGroupId>
      <geographyId>22519<geographyId>
      <geographyType>POSTAL_CODE</geographyType>
      <geographyName>90048</geographyName>
      <response>
        <field/>
        <code>SUCCESS</code>
        <message>Success</message>
      </response>
    </adGroupGeo>
  </adGroupGeos>
</results>

Example 5: JSON response for modified metro target

{
   "adGroupGeos": [
      {
         "adGroupId": "78",
         "geographyId": "66450",
         "geographyType": "MARKET",
         "geographyName": "Portsmouth, OH",
         "response": {
            "field": "",
            "message": "Success",
            "code": "SUCCESS"
         }
      }
   ]
}

Example 6: XML response for modified metro target

<results>
  <adGroupGeos>
    <adGroupGeo>
      <adGroupId>78</adGroupId>
      <geographyId>81971</geographyId>
      <geographyType>MARKET</geographyType>
      <geographyName>Portsmouth, OH</geographyName>
      <response>
        <field/>
        <code>SUCCESS</code>
        <message>Success</message>
      </response>
    </adGroupGeo>
  </adGroupGeos>
</results>

Example 7: JSON response for modified neighborhood target

{
   "adGroupGeos": [
      {
         "adGroupId": "78",
         "geographyId": "129455",
         "geographyType": "NEIGHBORHOOD",
         "geographyName": "East Highland Village",
         "response": {
            "field": "",
            "message": "Success",
            "code": "SUCCESS"
         }
      }
   ]
}

Example 8: XML response for modified neighborhood target

<results>
  <adGroupGeos>
    <adGroupGeo>
      <adGroupId>1001</adGroupId>
      <geographyId>129455</geographyId>
      <geographyType>NEIGHBORHOOD</geographyType>
      <geographyName>East Highland Village</geographyName>
      <response>
        <field/>
        <code>SUCCESS</code>
        <message>Success</message>
      </response>
    </adGroupGeo>
  </adGroupGeos>
</results>

Example 9: JSON response for modified province target

{
   "adGroupGeos": [
      {
         "adGroupId": "78",
         "geographyId": "82243",
         "geographyType": "STATE",
         "geographyName": "CA",
         "response": {
            "field": "",
            "message": "Success",
            "code": "SUCCESS"
         }
      }
   ]
}

Example 10: XML response for modified province target

<results>
  <adGroupGeos>
    <adGroupGeo>
      <adGroupId>1001</adGroupId>
      <geographyId>82243</geographyId>
      <geographyType>STATE</geographyType>
      <geographyName>CA</geographyName>
      <response>
        <field/>
        <code>SUCCESS</code>
        <message>Success</message>
      </response>
    </adGroupGeo>
  </adGroupGeos>
</results>

Example 11: Incorrectly formatted ad group ID

{
  "adGroupGeos": [
    {
      "adGroupId": "a78",
      "geographyId": "",
      "geographyType": "",
      "geographyName": "",
      "response": {
        "field": "adGroupId",
        "message": "The parameter adGroupId must be a number",
        "code": "PARAMETER_FORMAT"
      }
    }
  ]
}

AdGroupGeo API

Introduction

Contents

AdGroupGeo Get Endpoint

Request Parameters

Request Header Values

Request Examples

Example 1: Retrieve adgroup-geography associations for ad group 38

Example 2: Get the third page of results for ad group 38, three results per page, in XML

Response Properties

Response Examples

Example 1: A JSON success response

Example 2: An XML success response

Example 3: No authentication token (JSON)

Example 4: Missing required parameter (XML)

AdGroupGeo Mutate Endpoint

Request Parameters

Request Header Values

Request Examples

Example 1: Add Hudson, NY to ad group 78

Example 2: Remove Hudson, NY from ad group 78

Example 3: Add Postal Code 90048 to ad group 78

Example 4: Remove Postal Code 90048 from ad group 78

Example 5: Add Vinings, GA to ad group 1055

Example 6: Remove Vinings, GA from ad group 1055

Example 7: Add Sulphur Springs, TX Metro to ad group 1207

Example 8: Remove neighborhood East Highland Village, CA from ad group 1001

Example 9: Add California to ad group 78

Response Properties

Response Examples

Example 1: JSON response for modified city target

Example 2: XML response for modified city target

Example 3: JSON response for modified postal code target

Example 4: XML response for modified city target

Example 5: JSON response for modified metro target

Example 6: XML response for modified metro target

Example 7: JSON response for modified neighborhood target

Example 8: XML response for modified neighborhood target

Example 9: JSON response for modified province target

Example 10: XML response for modified province target

Example 11: Incorrectly formatted ad group ID