Regional availability

Every capture runs in a specific region. The AI apps we capture from tailor their answers to where the request appears to come from, so a query about “best running shoes” returns a different answer in the US than it does in Germany or Japan. The regions array lets you target that geography.

The regions array

regions is an array of region objects — at most 10 per request (more returns 422 TOO_MANY_REGIONS). Each object describes one place to capture from. When you omit regions entirely, each surface runs one untargeted capture — its child id carries the region key GLOBAL.

"regions": [{ "country": "US" }]

country

string

required

ISO-3166 alpha-2 country code (e.g. US, GB, DE, JP). This is the only required field in a region object. A bare string like "US" (or a flat country field) is accepted as sugar for { "country": "US" }.

state

string

Optional sub-national code or name (e.g. NY, California) to narrow targeting within the country.

city

string

Optional city name to narrow targeting further (e.g. London, San Francisco). Useful for locale-sensitive queries like local businesses or regional pricing.

language

string

Optional language hint for the capture (e.g. en, de, ja). When omitted, the surface uses its own default for the country.

location

string

Optional Google Ads geotarget canonical name (e.g. "Buffalo,New York,United States") that pins the Google surfaces (google_search, google_news, google_ai_overview, google_ai_mode) to a precise locality via a uule parameter — one of ~100,000 named cities, ZIPs, and boroughs from Google’s public geotargets list. It layers on top of the residential exit above (country/state/city), giving you named-locality targeting independent of the exit IP. Max 63 UTF-8 bytes. Applied only to Google surfaces; ignored by the others. If the name can’t be encoded, no locality is applied and a location_not_applied warning is returned rather than a wrong locality. See Local rank tracking & geo targeting for the full three-layer model.

Country coverage

The v1 residential exit network has the broadest, best-verified coverage in: US, GB, DE, FR, CA, AU, IN, JP, BR country accepts any valid ISO 3166-1 alpha-2 code — this list is where coverage is strongest, not an allowlist, so a valid country outside it is not rejected. The capture still runs; provenance.region.effective always reports where it actually ran. The only country-shape error is a malformed code (not two letters), which is a 400 VALIDATION_FAILED. GET /v1/regions returns the targeting shape and popular countries programmatically.

One child per surface × region

The most important rule: the API creates one child job for every combination of surface and region. Surfaces and regions multiply. If you request two surfaces across two regions, you get four children:

curl -X POST https://api.aisearchapi.dev/v1/search \
  -H "Authorization: Bearer $AISEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best noise-cancelling headphones",
    "surfaces": ["chatgpt", "perplexity"],
    "regions": [
      { "country": "US" },
      { "country": "GB", "city": "London", "language": "en" }
    ]
  }'

import os, requests

resp = requests.post(
    "https://api.aisearchapi.dev/v1/search",
    headers={"Authorization": f"Bearer {os.environ['AISEARCH_API_KEY']}"},
    json={
        "query": "best noise-cancelling headphones",
        "surfaces": ["chatgpt", "perplexity"],
        "regions": [
            {"country": "US"},
            {"country": "GB", "city": "London", "language": "en"},
        ],
    },
)
print(resp.json())

const resp = await fetch('https://api.aisearchapi.dev/v1/search', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AISEARCH_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'best noise-cancelling headphones',
    surfaces: ['chatgpt', 'perplexity'],
    regions: [
      { country: 'US' },
      { country: 'GB', city: 'London', language: 'en' },
    ],
  }),
});
console.log(await resp.json());

The parent response is a 202 with one child id per pairing:

{
  "jobId": "job_8t2q",
  "status": "processing",
  "children": [
    "job_8t2q.chatgpt.us",
    "job_8t2q.chatgpt.gb:london:en",
    "job_8t2q.perplexity.us",
    "job_8t2q.perplexity.gb:london:en"
  ]
}

Child ids have three dot-separated segments — job_<id>.<surface>.<regionKey>, where the region key is the lowercased country[:city][:language] (or GLOBAL for an untargeted capture). The acquisition method is deliberately not in the id. Fetch any child with GET /v1/jobs/:id to receive its Envelope, or poll the parent for the rollup. See Asynchronous jobs for the full polling flow.

Each capture is billed separately. surfaces × regions is exactly how many captures you pay for. Two surfaces across two regions is four captures, not two. See Credits & billing before fanning out across many regions.

Requested vs. effective region

We always try to honor the exact region you asked for. When a surface can’t be captured from precisely that location, we capture from the closest workable location instead and tell you — rather than silently returning something from the wrong place. Every Envelope reports both values under provenance.region:

provenance.region.requested

string | null

The region you asked for. null for an untargeted capture.

provenance.region.effective

string | null

The region the capture actually ran from. When it matches requested, the region was honored exactly. When it differs, the surface answered from effective instead.

For a capture that was honored exactly:

{
  "provenance": {
    "region": {
      "requested": "gb:london:en",
      "effective": "gb:london:en"
    }
  }
}

When only the city could not be honored, effective falls back to the broader region:

{
  "provenance": {
    "region": {
      "requested": "gb:inverness:en",
      "effective": "gb:en"
    }
  }
}

Always read provenance.region.effective — not your original request — when you attribute a result to a geography. Comparing the two fields tells you whether a locale-sensitive answer can be trusted at city precision.

Choosing regions

Global market coverage

List one region object per market you care about. Because every surface runs in every region, you get a clean matrix — the same parser handles job_<id>.chatgpt.us and job_<id>.chatgpt.de identically.

Language variations within a country

Add the language field to capture the same country in different languages (e.g. { "country": "DE", "language": "de" } and { "country": "DE", "language": "en" }). Each is a separate capture and a separate child.

City-level local intent

For queries with strong local intent — nearby businesses, regional availability, local pricing — set city (and optionally state). If the city can’t be honored, effective shows you the fallback so you know the precision you actually got.

Introduction

Guides

The regions array

Country coverage

One child per surface × region

Requested vs. effective region

Choosing regions

Next steps

Credits & pricing

Search API reference

​The regions array

​Country coverage

​One child per surface × region

​Requested vs. effective region

​Choosing regions

​Next steps

Credits & pricing

Search API reference

The regions array

Country coverage

One child per surface × region

Requested vs. effective region

Choosing regions

Next steps