ChatGPT Ads
Publicité ChatGPT

Ciblage géographique des campagnes dans l'API Ads (Campaign Targeting)

Idée centrale

L'API Ads permet de cibler géographiquement une campagne par pays, région ou DMA (« Designated Market Area », zone de marché télévisuel/publicitaire nord-américaine). Le ciblage repose sur deux étapes : rechercher des identifiants de localisation via un endpoint dédié (geo_lookup/search), puis les appliquer au champ targeting.locations.include lors de la création (ou mise à jour) d'une campagne — voir Campagnes et annonces dans l'API Ads.

Définition

L'endpoint GET /geo_lookup/search de l'API Ads, associé au champ targeting.locations.include de la ressource campagne, qui permettent de rechercher puis d'appliquer un ciblage géographique par programmation.

Contexte

Cette page n'est pas elle-même une page de référence api-reference/ : c'est un guide fonctionnel qui utilise l'endpoint de création de campagne (POST /campaigns, documenté dans Campagnes et annonces dans l'API Ads) pour illustrer un cas d'usage précis, tout en introduisant un endpoint distinct propre au ciblage (geo_lookup/search) qui n'appartient à aucune des pages de référence api-reference/. Capturée le 2026-08-08.

Fonctionnement

curl -G "https://api.ads.openai.com/v1/geo_lookup/search" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  --data-urlencode "q=San Francisco" \
  --data-urlencode "limit=5"
ParamètreDescription
qTexte de recherche (ex. « San Francisco »).
limitNombre maximal de résultats.

La réponse contient count, query, et un tableau results, chaque résultat exposant : id (identifiant de localisation, ex. "3000194"), type (ex. "dma"), canonical_name (nom complet, ex. « San Francisco - Oakland - San Jose, United States »), country_code (ex. "US"), name (nom affiché court), region_code (ex. "807").

Catalogue complet en CSV

Un lien de téléchargement fournit l'ensemble du catalogue de localisations ciblables (openai-geotargets.csv), utile pour une recherche hors ligne plutôt qu'un appel API par requête.

Application à une campagne

À la création d'une campagne (POST /campaigns), le ciblage se déclare via targeting.locations.include, une liste d'objets ne nécessitant que le champ id — l'API complète automatiquement les détails de localisation correspondants dans la campagne enregistrée. Si aucun ciblage n'est fourni, la campagne peut cibler toutes les localisations disponibles par défaut.

curl -X POST "https://api.ads.openai.com/v1/campaigns" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: campaign-targeting-example-1" \
  -d '{
    "name": "West Coast launch",
    "status": "paused",
    "budget": { "lifetime_spend_limit_micros": 25000000 },
    "bidding_type": "clicks",
    "targeting": {
      "locations": {
        "include": [
          { "id": "2000043" },
          { "id": "3000194" },
          { "id": "3000001" }
        ]
      }
    }
  }'
Identifiant de localisationSignificationType
2000043California, United Statesregion
3000194San Francisco - Oakland - San Jose, United Statesdma
3000001New York, United Statesdma

L'exemple illustre aussi l'usage d'un en-tête Idempotency-Key sur POST /campaigns, non mentionné par la page de référence Campaigns elle-même.

Statuts de campagne pendant la validation

Utiliser status: "paused" pendant la validation de la configuration, puis basculer vers "active" une fois la campagne, ses groupes d'annonces et ses annonces prêts à diffuser.

Éléments essentiels

Distinctions importantes

Ne pas confondre les identifiants de localisation de type region (ex. un État américain) et dma (zone de marché télévisuelle, plus fine géographiquement) : les deux sont acceptés dans targeting.locations.include, sans hiérarchie explicite documentée entre eux.

Cas pratiques

Aucun cas pratique disponible : identifiants et exemples (West Coast launch, San Francisco) manifestement fictifs et illustratifs, bien qu'utilisant des noms de lieux réels.

Erreurs fréquentes

Ne pas oublier qu'omettre targeting.locations à la création d'une campagne cible potentiellement toutes les localisations disponibles : ce comportement par défaut, large, peut ne pas correspondre à l'intention si le ciblage était censé être requis.

Ne pas confondre l'endpoint geo_lookup/search (recherche interactive) avec le catalogue CSV téléchargeable (openai-geotargets.csv, recherche hors ligne) : deux façons d'obtenir les mêmes identifiants, adaptées à des cas d'usage différents.

Limites et nuances

Relations

Points à vérifier

Sources