|
|
GeographicalDictionaryService
GeographicalDictionaryService is a lookup service that includes operations to search for geographical locations (represented by GeoLocation objects).
The GeoLocation objects represent a targetable area and they are hierarchical in nature. For example, a GeoLocation object representing a country contains GeoLocation objects that can represent States, and a State GeoLocation object can contain GeoLocation objects that represent Cities, and so on. The levels and depth of hierarchy depend on the market area.
The service contains operations to retrieve geographical locations based on either WOEID, or name of the area (such as the name of Country, State, City), or radial distance from a well-known geographical location. Each geographical location is mapped to a WOEID which is unique to a given market. The mapping between GeoLocation object and WOEID is immutable and we recommended that you store the mapping and use the WOEID directly in the API calls.
Operations
- getAncestorGeoLocations
- getGeoLocation
- getGeoLocations
- getGeoLocationsByParentByLevel
- getGeoLocationsByString
- getGeoLocationsByStringByCountry
- getGeoLocationsByStrings
- getTargetableGeoLevels
- getTopLevelGeoLocations
- getZipGeoLocationsWithinRadius
getAncestorGeoLocations
Retrieve the list of geographical locations that are ancestors of the specified geographical location WOEID.
Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web, Mobile
Parameters
| Parameter | Data Type | Description |
|---|---|---|
| geoLocationWOEID | long | The WOEID of the geographical location for which the ancestors are needed. |
Response
GeoLocation[] - The list of geographical locations that are ancestors of the specified geographical location.
getGeoLocation
Retrieve the geographical location details for the specified WOEID.
Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web, Mobile
Parameters
| Parameter | Data Type | Description |
|---|---|---|
| geoLocationWOEID | long | The WOEID of the geographical location to retrieve. |
Response
GeoLocation - The geographical location details.
getGeoLocations
Retrieve a list of geographical locations (based on the WOEIDs). This operation accepts a maximum of 100 (geographical locations') WOEIDs as input. If more than 100 WOEIDs are specified, this operation retrieves details for only the first 100 WOEIDs and the rest are discarded.
Note: This operation is same as the getGeoLocation() operation except that this is used to retrieve multiple geographical locations, and the order of WOEIDs returned may be different from the order in the input.
Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web, Mobile
Parameters
| Parameter | Data Type | Description |
|---|---|---|
| geoLocationWOEIDs | long[] | The WOEIDs of the geographical locations to retrieve. |
Response
GeoLocation[] - The list of geographical locations.
getGeoLocationsByParentByLevel
Retrieve all the geographical locations at the specified level which are children of the specified parent.
Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web, Mobile
Parameters
| Parameter | Data Type | Description |
|---|---|---|
| parentWOEID | long | The WOEID of the parent (geographical location). |
| geoLevel | TargetingType | The level at which the children of the specified parent WOEID are requested. |
| startElement | int | The first element to retrieve (0-based; if a value <= 0 is entered, it will default to 0). |
| numElements | int | The number of elements to retrieve (1000 maximum; if a value <=0 is entered, it will default to 1000). |
Response
GeoLocation[] - The list of geographical locations at the specified level for the given parent WOEID.
getGeoLocationsByString
Retrieve the geographical locations matching the specified name.
Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web, Mobile
Parameters
| Parameter | Data Type | Description |
|---|---|---|
| geoString | string | The geographical location name. |
Response
GeoLocationProbability[] - The list of geographical locations that match the specified name.
getGeoLocationsByStringByCountry
Retrieve the geographical locations that match the specified geographical location name in the specified country.
Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web, Mobile
Parameters
| Parameter | Data Type | Description |
|---|---|---|
| geoString | string | The name of the geographical location. |
| countryWOEID | long | The WOEID of the country. |
Response
GeoLocationProbability[] - The list of geographical locations that match the specified geographical location name in the specified country.
getGeoLocationsByStrings
Retrieve the geographical locations matching the specified names. This operations accepts a maximum of 100 strings as input. If more than 100 strings are specified, this operation uses only the first 100 specified strings and the remaining strings are discarded.
Note: This is similar to the getGeoLocationsByString() except that here multiple strings, representing geographical locations' names are passed for matching. A maximum of 1000 matches will be returned.
Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web, Mobile
Parameters
| Parameter | Data Type | Description |
|---|---|---|
| geoStrings | string[] | The names of geographical locations. |
Response
GeoLocationProbabilitySet[] - The list of geographical locations that match the specified names.
getTargetableGeoLevels
Retrieve the list of TargetingType objects for the specified market. A TargetingType object represents the levels at which targets can be created.
Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web, Mobile
Parameters
none
Response
TargetingType[] - The list of TargetingType objects (representing the available and supported geographical levels that can be targeted)
getTopLevelGeoLocations
Retrieve all the top level geographical locations (for the market to which user/license belongs).
Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web, Mobile
Parameters
none
Response
GeoLocation[] - The list of top level geographical locations.
getZipGeoLocationsWithinRadius
Retrieve the list of ZIP level geographical locations that are located within the specified radius of a ZIP level geographical location WOEID. The maximum radius that can be specified is 10 miles.
Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web, Mobile
Parameters
| Parameter | Data Type | Description |
|---|---|---|
| radius | long | The radius within which the geographical locations are requested. |
| distanceUnits | DistanceUnits | Unit of Distance. |
| zipWOEID | long | The WOEID of the ZIP level geographical location for which the ZIP level geographical locations are requested. |
| startElement | int | The first element to retrieve (0-based; if a value <= 0 is entered, it will default to 0). |
| numElements | int | The number of elements to retrieve (1000 maximum; if a value <=0 is entered, it will default to 1000). |
Response
GeoLocation[] - The list of geographical locations that are within the given radius of the specified geographical location.