Match stale location targeting to current places with AI

Reference

POST https://YOUR-NETWORK-DOMAIN/rest-api/targeting/stale-locations/suggestions.do

The suggestions of GET on this path, with the places names leave open sent to the AI assistant's model, which picks only from the geo database's own list: in as few calls as the lists allow, at most 12 of up to 60 places, four at a time, and the request waits for them at most two minutes. It runs and is billed like the AI assistant - it needs the AI_ASSISTANT_CHAT permission, a key and monthly budget left, and the budget is checked again before each call after the first four. A place another request is asking about at the same moment is not asked twice. Rules naming the same stale place with the same include or exclude form one group, with its 'targetIds', how many rules of each kind and how many entities of each level carry them. 'suggestion.action' is REPLACE (apply with POST replace.do: targetIds, countryCode, regionName, cityName as the suggestion gives them), REMOVE (no current place matches, and removing the rules changes nothing: POST remove.do) or KEEP (nothing is proposed: removing the rules would change delivery, or the geo service did not answer for the place; the user decides). A city whose region is gone is looked for under up to 80 of the country's regions; where the country has more, not finding it there is a NO_SUCCESSOR of LOW confidence. 'reason' is SPELLING, SUFFIX (an administrative word such as "County" or "Stationsby" dropped), REGION_RENAMED, RENAMED, MERGED, NO_SUCCESSOR, NOT_MATCHED, COUNTRY_RULE or GEO_UNANSWERED, with 'reasonParams' (old name, new name) and 'reasonText' in the user's language; 'confidence' is HIGH, MEDIUM or LOW; 'source' says whether names (DETERMINISTIC) or the AI assistant's model (AI) matched it. 'ai' says what happened: USED, NOT_NEEDED (every place was answered already), DISABLED, PERMISSION, NO_KEY, LIMIT or FAILED; without the model the suggestions come from names alone and 'aiMessage' says why. Answers are kept in the server's memory for up to a week, until it restarts, for every user. Nothing is changed. Requires MANAGE_DEMAND_TARGETING or MANAGE_SUPPLY_PRE_TARGETING.

Responses

200

{success, status: OK|GEO_UNAVAILABLE, unavailable, message, ai, aiMessage, groups:[{type, value, place, rule, targetIds, kinds:{SAFE, OPENS_ALL, STARTS_DELIVERY}, entities:{ADVERTISER, CAMPAIGN, BANNER, SITE, ZONE, PLACEMENT}, suggestion:{action, countryCode, regionName, cityName, newPlace, reason, reasonParams, reasonText, confidence, source}}]}

400

Bad request — invalid or missing parameters

401

Authentication error

403

The role lacks both MANAGE_DEMAND_TARGETING and MANAGE_SUPPLY_PRE_TARGETING

Language

cURL Request

curl --request POST \
  --url 'https://YOUR-NETWORK-DOMAIN/rest-api/targeting/stale-locations/suggestions.do' \
  --header 'X-Api-Key: YOUR_API_KEY'

Python Request

import requests

response = requests.request("POST", "https://YOUR-NETWORK-DOMAIN/rest-api/targeting/stale-locations/suggestions.do", headers={"X-Api-Key": "YOUR_API_KEY"})
print(response.json())

Node Request

const response = await fetch('https://YOUR-NETWORK-DOMAIN/rest-api/targeting/stale-locations/suggestions.do', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
});

console.log(await response.json());

Java Request

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://YOUR-NETWORK-DOMAIN/rest-api/targeting/stale-locations/suggestions.do"))
    .header("X-Api-Key", "YOUR_API_KEY")
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

C# Request

using var client = new HttpClient();

var request = new HttpRequestMessage(new HttpMethod("POST"), "https://YOUR-NETWORK-DOMAIN/rest-api/targeting/stale-locations/suggestions.do");
request.Headers.Add("X-Api-Key", "YOUR_API_KEY");

var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

Go Request

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://YOUR-NETWORK-DOMAIN/rest-api/targeting/stale-locations/suggestions.do", nil)
	req.Header.Set("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}

PHP Request

<?php
$ch = curl_init("https://YOUR-NETWORK-DOMAIN/rest-api/targeting/stale-locations/suggestions.do");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Api-Key: YOUR_API_KEY"]);

echo curl_exec($ch);
curl_close($ch);

Ruby Request

require 'net/http'
require 'json'

uri = URI("https://YOUR-NETWORK-DOMAIN/rest-api/targeting/stale-locations/suggestions.do")
request = Net::HTTP::Post.new(uri)
request['X-Api-Key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
puts response.body