GeographicalTargetingService contains operations for retrieving standard geographic information and managing custom geographic zones.
getAncestorRegions
Get allthe parents (ancestors) of a region.
Capability required: AccountRead
License command group: NetworkManagement
Parameters
| Parameter | Data Type | Description | Restriction |
|---|---|---|---|
| regionWOEID | long | The WOEID of the region. | Req |
Response
Region[] - The list of parent regions for the specified region. For example, for Los Angeles, the operation will return California, United States (parent/ancestor regions).
getCountries
Get all countries.
Capability required: AccountRead
License command group: NetworkManagement
Parameters
none
Response
Region[] - The list of countries.
getExtendedName
Get the extended name of a region.
Capability required: AccountRead
License command group: NetworkManagement
Parameters
| Parameter | Data Type | Description | Restriction |
|---|---|---|---|
| regionWOEID | long | The WOEID of the region. | Req |
Response
string - The extended name of the region. For example, for Los Angeles, the operation will return Los Angeles, California, United States.
getRegion
Get a region.
Capability required: AccountRead
License command group: NetworkManagement
Parameters
| Parameter | Data Type | Description | Restriction |
|---|---|---|---|
| regionWOEID | long | The WOEID of the region. | Req |
Response
Region - The region associated with the specified WOEID.
getRegionLevelsForCountry
Get the level definitions for a country.
Capability required: AccountRead
License command group: NetworkManagement
Parameters
| Parameter | Data Type | Description | Restriction |
|---|---|---|---|
| countryWOEID | long | The WOEID of the country. | Req |
Response
RegionLevel[] - The list of applicable and available levels for the specified country.
getRegions
Get a list of regions.
Quota is charged for each object in the request.
Capability required: AccountRead
License command group: NetworkManagement
Parameters
| Parameter | Data Type | Description | Restriction |
|---|---|---|---|
| regionWOEIDs | long[] | The WOEIDs of the regions (1000 maximum. if > 1000, will default to first 1000). | Req |
Response
Region[] - The list of regions associated with the specified WOEIDs.
getRegionsByLevelWithinRadius
Get regions at a level that are within a radius of a specified region.
Capability required: AccountRead
License command group: NetworkManagement
Parameters
| Parameter | Data Type | Description | Restriction |
|---|---|---|---|
| radius | long | The maximum radius. | Req |
| distanceUnits | DistanceUnits | The unit of measurement for radius. | Req |
| regionWOEID | long | The WOEID of the region around which the regions are requested. | Req |
| level | long | The level of the requested regions. | Req |
| startElement | int | The first element to retrieve (0-based; if a value <= 0 is entered, it will default to 0). | Req |
| numElements | int | The number of elements to retrieve (1000 maximum; if a value <=0 is entered, it will default to 1000). | Req |
Response
Region[] - The list of regions at the specified level and within the specified radius of the specified region.
getRegionsByParentByLevel
Get all regions at a given level for the specified parents. For example, if you need all regions at level=3 for parent 1000 (which is at level=1), pass in 1000 as parentWOEID and 3 as level.
NOTE: Level is relative to the country to which it applies and it is not constant. For example, if level=3 represents State in one country, it may not necessarily be the case for all countries.
Quota is charged for each object in the request.
Capability required: AccountRead
License command group: NetworkManagement
Parameters
| Parameter | Data Type | Description | Restriction |
|---|---|---|---|
| parentWOEIDs | long[] | The WOEIDs of the parent (at a level higher than the requested level). | Req |
| level | long | The level at which the regions are requested. | Req |
| startElement | int | The first element to retrieve (0-based; if a value <= 0 is entered, it will default to 0). | Req |
| numElements | int | The number of elements to retrieve (1000 maximum; if a value <=0 is entered, it will default to 1000). | Req |
Response
Region[] - All regions at the specified level for the specified parent WOEIDs. If there is no information available at the given level for the specified parent, a null response is returned for that WOEID.
getRegionsByString
Get a region that match a region name (up to a max of 1000 results).
Capability required: AccountRead
License command group: NetworkManagement
Parameters
| Parameter | Data Type | Description | Restriction |
|---|---|---|---|
| regionName | string | The name of the region to search for. | Req |
Response
RegionProbability[] - The list of regions that match the given region name.
getRegionsByStringByCountry
Get the regions that match a region name in the specified country (up to a max of 1000 results).
Capability required: AccountRead
License command group: NetworkManagement
Parameters
| Parameter | Data Type | Description | Restriction |
|---|---|---|---|
| regionName | string | The name of the region to search for. | Req |
| countryWOEID | long | The WOEID of the country. | Req |
Response
RegionProbability[] - The list of regions that match the given region name in the specified country.