Geotargeting API Examples

Search for a geotarget

To search for a geotarget by name, you can use the GET /geo/api/search/v2/geo endpoint.

Specify:

geo_types

Type of geopgrahic area you are searching for:

  • country

  • metro

  • region

  • city

  • postalcode

starts_with

Segment that you want to query

For example, to search for a city named Austin:

Request:

curl --user dev@example.com \
"https://services.adroll.com/geo/api/search/v2/geo?apikey=MYAPIKEY&geo_types=city&starts_with=austin"

Response:

{
    "results": [
        {
            "country": {
                "iso2": "US",
                "name": "United States"
            },
            "eid": "PVVKZWCOHFH3XNYZKX8GEO",
            "name": "Austin",
            "name_localized": null,
            "type": "city"
        }
    ]
}

Attach a GeoTarget to an AdGroup

curl --location --request POST 'https://services.adroll.com/api/v1/adgroup/create?apikey=MYAPIKEY' \
    --user 'dev@example.com' \
    --form 'advertisable="ADVERTISABLE_EID"' \
    --form 'name="OI"' \
    --form 'campaign="CAMPAIGN_EID"' \
    --form 'geo_targets="[{\"eid\": \"PVVKZWCOHFH3XNYZKX8GEO\", \"is_negative\": false}]"'

Response:

{
    "results": {
        "status": "approved",
        "updated_date": "2021-01-25 14:42:40",
        "coops": [],
        "ad_optimization": "",
        "campaign": "CAMPAIGN_EID",
        "site_exclusions": [],
        "platform_targets": [],
        "type": "sites",
        "segments": [],
        "ads": [],
        "geo_targets": [],
        "placement_targets": [],
        "eid": "ADGROUP_EID",
        "is_cats4gold": false,
        "created_date": "2021-01-25 14:42:40",
        "demographic_targets": [],
        "space_optimization": "",
        "flight_timezone": "UTC",
        "name": "OI"
    }
}

Then you can check if the GeoTargets were correctly attached with the following API call:

curl --location \
    --request GET \
    --user 'dev@example.com' \
    'https://services.adroll.com/geo/api/targets/v1/target/ADGROUP_EID?apikey=MYAPIKEY'

Response:

{
    "data": [
        {
            "city": {
                "country_code": "US",
                "eid": "PVVKZWCOHFH3XNYZKX8GEO",
                "id": 315714,
                "is_facebook_target": false,
                "name": "Austin",
                "name_localized": null,
                "region_code": "PA",
                "region_name": "Pennsylvania",
                "type": "city"
            },
            "country": {
                "code": "US",
                "country": "US",
                "eid": "TTWGSKZDVNAVNKJ7GJ8GEO",
                "id": 232,
                "is_facebook_target": true,
                "name": "United States",
                "server_id": 232,
                "type": "country"
            },
            "geo_eid": "PVVKZWCOHFH3XNYZKX8GEO",
            "metro": {
                "boundaries": "NY-PA",
                "country": "US",
                "country_code": "US",
                "eid": "LPU5NINNNJHI3H72QS8GEO",
                "id": 514,
                "is_facebook_target": null,
                "name": "Buffalo, NY",
                "server_id": 514,
                "type": "metro"
            },
            "name": "Austin",
            "operation": "include",
            "postalcode": null,
            "region": {
                "country": "US",
                "eid": "O5OINHGRIVHJ5GTZAJ8GEO",
                "id": "USPA",
                "is_facebook_target": true,
                "name": "Pennsylvania",
                "name_localized": null,
                "region": "PA",
                "type": "region"
            },
            "type": "city"
        }
    ],
    "eid": "ADGROUP_EID"
}