Search targeting options

curl --request GET \
  --url https://api.aisa.one/apis/v1/ads/targeting/search \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.aisa.one/apis/v1/ads/targeting/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aisa.one/apis/v1/ads/targeting/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.aisa.one/apis/v1/ads/targeting/search"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.aisa.one/apis/v1/ads/targeting/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "id": "<string>",
      "name": "<string>",
      "type": "<string>",
      "audienceSize": 123,
      "countryCode": "<string>",
      "path": [
        "<string>"
      ],
      "platformId": "<string>",
      "status": "<string>"
    }
  ]
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "retryHint": "<string>",
    "retryable": true,
    "type": "<string>"
  }
}

AIsa Ads

Search targeting options

Ad Targeting. Read only. Finds targeting options by name, such as locations, interests or behaviors, and returns the ids to use in ad targeting. It resolves a human-readable query into the platform's opaque targeting ids used in the `TargetingSpec`: the `countries`/`regions`/`cities`/`zips`/`metros` geo keys and the `interests`/`behaviors` entity ids.  A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.

GET

https://api.aisa.one

apis

ads

targeting

Search targeting options

curl --request GET \
  --url https://api.aisa.one/apis/v1/ads/targeting/search \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.aisa.one/apis/v1/ads/targeting/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aisa.one/apis/v1/ads/targeting/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.aisa.one/apis/v1/ads/targeting/search"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.aisa.one/apis/v1/ads/targeting/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "id": "<string>",
      "name": "<string>",
      "type": "<string>",
      "audienceSize": 123,
      "countryCode": "<string>",
      "path": [
        "<string>"
      ],
      "platformId": "<string>",
      "status": "<string>"
    }
  ]
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "retryHint": "<string>",
    "retryable": true,
    "type": "<string>"
  }
}

Request contract

Method and path: GET /apis/v1/ads/targeting/search
Availability: enabled
Request URL template: https://api.aisa.one/apis/v1/ads/targeting/search
connectionId: query; required
q: query; required
dimension: query; optional
geoType: query; optional
countryCode: query; optional
adAccountId: query; optional
locale: query; optional
limit: query; optional
Runtime facts: fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09

Complete OpenAPI definition Effective request and pricing declaration (including authentication and referenced schemas):

{
  "operationId": "get_aisa_ads_apis_v1_ads_targeting_search",
  "method": "GET",
  "path": "/apis/v1/ads/targeting/search",
  "servers": [
    {
      "url": "https://api.aisa.one"
    }
  ],
  "parameters": [
    {
      "description": "The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead.",
      "in": "query",
      "name": "connectionId",
      "required": true,
      "schema": {
        "pattern": "^adc_[0-9A-Za-z]+$",
        "type": "string"
      }
    },
    {
      "description": "Search query. For geo, the locality name only (no region/country suffix). For `interestSuggestion`, the interest names: comma-separated, or a JSON array of strings when a name contains a comma (a `q` starting with `[` is read as JSON).",
      "in": "query",
      "name": "q",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "What to search. Defaults to `interest` for backward compatibility with the deprecated /apis/v1/ads/interests alias. `geo`: resolves locations (scope further with `geoType`).",
      "in": "query",
      "name": "dimension",
      "required": false,
      "schema": {
        "default": "interest",
        "enum": [
          "geo",
          "interest",
          "interestSuggestion",
          "interestKeyword",
          "behavior",
          "hashtag",
          "income",
          "language",
          "workPosition",
          "workEmployer",
          "workIndustry",
          "industry",
          "jobFunction",
          "seniority",
          "companySize",
          "skill",
          "community",
          "conversationKeyword"
        ],
        "type": "string"
      }
    },
    {
      "description": "Only used when `dimension=geo`. The kind of location to resolve. `all` searches every type in one relevance-ranked call. Defaults to `city`.",
      "in": "query",
      "name": "geoType",
      "required": false,
      "schema": {
        "default": "city",
        "enum": [
          "all",
          "country",
          "country_group",
          "region",
          "city",
          "subcity",
          "neighborhood",
          "place",
          "zip",
          "metro_area",
          "geo_market"
        ],
        "type": "string"
      }
    },
    {
      "description": "ISO 3166-1 alpha-2 country code (e.g. NL) to scope a geo search.",
      "in": "query",
      "name": "countryCode",
      "required": false,
      "schema": {
        "maxLength": 2,
        "minLength": 2,
        "type": "string"
      }
    },
    {
      "description": "TikTok only: the advertiser to search as, when the connection holds several. Each TikTok advertiser has its own targetable regions and catalogs.",
      "in": "query",
      "name": "adAccountId",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Meta only (ignored on other platforms). The language Meta matches `q` against and names results and `path` in, as language_TERRITORY (e.g. `pl_PL`, `en_US`).",
      "in": "query",
      "name": "locale",
      "required": false,
      "schema": {
        "pattern": "^[a-z]{2,3}_[A-Z]{2}$",
        "type": "string"
      }
    },
    {
      "description": "Maximum results to return.",
      "in": "query",
      "name": "limit",
      "required": false,
      "schema": {
        "default": 25,
        "maximum": 100,
        "minimum": 1,
        "type": "integer"
      }
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "x-aisa-status": "enabled",
  "x-aisa-pricing": {
    "description": "Ads operations are free. Ad spend is billed by the ad platform to the connected ad account, never by AIsa.",
    "kind": "no_customer_charge"
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "scheme": "bearer",
        "type": "http"
      }
    }
  }
}

Cost and request rules

A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. Published reference values are not an account-specific quote or a settled charge. For endpoints supporting X-AISA-Cost-Mode: quote, obtain a free quote for your exact request before execution; reconcile the settled cost with response metadata and Usage Logs. USD amounts use 1,000,000 integer micro-USD per dollar.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

connectionId

string

required

The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead.

Pattern: ^adc_[0-9A-Za-z]+$

string

required

Search query. For geo, the locality name only (no region/country suffix). For interestSuggestion, the interest names: comma-separated, or a JSON array of strings when a name contains a comma (a q starting with [ is read as JSON).

dimension

enum<string>

default:interest

What to search. Defaults to interest for backward compatibility with the deprecated /apis/v1/ads/interests alias. geo: resolves locations (scope further with geoType).

Available options:

geo,

interest,

interestSuggestion,

interestKeyword,

behavior,

hashtag,

income,

language,

workPosition,

workEmployer,

workIndustry,

industry,

jobFunction,

seniority,

companySize,

skill,

community,

conversationKeyword

geoType

enum<string>

default:city

Only used when dimension=geo. The kind of location to resolve. all searches every type in one relevance-ranked call. Defaults to city.

Available options:

all,

country,

country_group,

region,

city,

subcity,

neighborhood,

place,

zip,

metro_area,

geo_market

countryCode

string

ISO 3166-1 alpha-2 country code (e.g. NL) to scope a geo search.

Required string length: 2

adAccountId

string

TikTok only: the advertiser to search as, when the connection holds several. Each TikTok advertiser has its own targetable regions and catalogs.

locale

string

Meta only (ignored on other platforms). The language Meta matches q against and names results and path in, as language_TERRITORY (e.g. pl_PL, en_US).

Pattern: ^[a-z]{2,3}_[A-Z]{2}$

limit

integer

default:25

Maximum results to return.

Required range: 1 <= x <= 100

Response

Matching targeting options (normalized)

results

object[]

Show child attributes

​Request contract

​Cost and request rules

Authorizations

Query Parameters

Response

Request contract

Cost and request rules