Locations and provider dictionaries

ProxyRequest separates the location a customer asks for from the value an upstream provider expects. The canonical catalog gives customers one stable vocabulary. A provider dictionary translates that vocabulary into the provider’s country, region, city, and ASN grammar.

What happens on a new installation

The installation bootstrap imports the platform’s canonical continents, countries, regions, cities, ASNs, and ISPs. The locations service then keeps normalized snapshots available to the gateway and refreshes them when the source hash changes. You do not need to recreate the global country list for every provider.

After first startup:

open Locations → Countries and confirm that the canonical rows exist;
open Locations → Location dictionaries and check which provider dictionaries are already present;
import a provider’s current vocabulary from its API when an adapter is available, or create the mapping manually;
attach that dictionary when importing or editing the provider;
test the narrowest location you intend to sell before enabling it on a package.

Countries page showing the current canonical country columns and records — The canonical country catalog is installed once and is shared by provider dictionaries and customer targeting.
Use the page controls to search, sort, create, or export the canonical catalog.
The table exposes the real country contract: name, original name, alpha-2, alpha-3, and numeric codes.

Review location dictionaries

Location Dictionaries page showing provider coverage counts — A dictionary shows which providers use it and how much vocabulary it currently covers.
Create a manual dictionary or start the provider API import from the page controls.
Coverage columns make missing countries, regions, cities, or ASN mappings visible before launch.

Use one dictionary per provider grammar unless two integrations are proven to accept exactly the same values. A dictionary can be reused by multiple provider records when their location syntax is identical.

Import a dictionary from a provider API

Choose Import when the provider adapter can read the upstream location catalog. Credentials entered in the wizard are used for that import request and are not displayed in the final review.

Select the provider adapter.
Enter the authentication method required by that provider.
Set a bounded timeout and retry count.
Review the source and secret-handling summary.
Start the import and wait for a success result before attaching the dictionary to production routing.

Location dictionary import wizard provider source step — Step 1 selects the adapter that knows how to read and normalize the provider's location API.
Choose the provider location API source; do not select a similar brand by guesswork.
The stepper makes the four import decisions explicit before any write occurs.

Location dictionary import wizard authentication step — Step 2 supplies only the credentials needed to read the upstream catalog.
Use a provider token or credential pair with the smallest practical scope.
Import secrets are session-only inputs and are not shown again in the review.

Location dictionary import timeout and retry settings — Step 3 bounds how long a slow or unavailable provider API can hold the import.
Timeout and retry policy should fit the provider API without turning an outage into an endless job.
The summary confirms the adapter and authentication mode before review.

Location dictionary import review and start action — Step 4 is the final write boundary. Confirm the source before starting the import.
Review source, authentication mode, timeout, and retry settings together.
Start the provider API import only after the summary matches the intended account.

After import, compare counts with the provider’s own catalog and test examples from every advertised level. A successful import proves that data was read and normalized; it does not prove that every location currently has usable proxy inventory.

Create a dictionary manually

Use manual creation when no adapter exists, the provider publishes a static mapping, or you need a controlled override. Start with country mappings, verify them, then add region, city, and ASN only as required.

Manual location dictionary creation general tab — Give the dictionary an operator-readable identity before entering provider translations.
Name the dictionary after the provider grammar and environment, not after a customer package.
Provider translations are a separate workspace so general identity stays easy to review.

Manual provider country vocabulary and replacement mappings — Vocabulary records accepted values; replacements translate canonical values into provider-specific tokens.
List provider country vocabulary using values confirmed by its API or documentation.
Map each canonical country to the exact provider replacement sent in upstream credentials.

The same pattern applies to region, city, and ASN. Preserve parent context: a city mapping without the correct country and region can be ambiguous. Avoid silent fallbacks that widen a request from city to country unless that is an explicit product rule.

How location data reaches a request

canonical customer target
        ↓
package exposes the dimension
        ↓
routing filters eligible providers
        ↓
provider dictionary translates the value
        ↓
provider credential builder sends its grammar upstream

The locations service uses normalized, versioned snapshots so gateways can read a consistent dataset. Provider-specific formats stay at the translation boundary; customers and packages continue to use canonical values.

Validation checklist

Catalog

Canonical countries and the required child locations exist after startup.

Translation

Provider values and replacements match real upstream examples.

Availability

Package-visible targets are backed by an eligible provider and protocol.

Live test

Exit IP and reported geography match a broad and narrow requested target.

If an import fails, keep the last known-good dictionary attached, check provider credentials and API reachability, and retry with a bounded policy. If the provider changed its grammar, test a replacement dictionary before switching live routes.

Continue with provider configuration to connect endpoints and credentials to the verified dictionary.