Locations

GET /locations returns the geo catalog you can target: every country, its states or regions, and their cities, in exactly the code form the proxy-list generator and whitelist defaults expect.

Scope: read

Get the catalog

curl https://dashboard.proxio.net/api/v1/locations \
  -H "Authorization: Bearer pxo_9fJ2kQ7xR4mN8pL1dW6vB3cH5tZ0aYqS7dK2mN9x"

import requests

BASE = "https://dashboard.proxio.net/api/v1"
API_KEY = "pxo_9fJ2kQ7xR4mN8pL1dW6vB3cH5tZ0aYqS7dK2mN9x"

resp = requests.get(
    f"{BASE}/locations",
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=15,
)
resp.raise_for_status()
for country in resp.json()["data"]["countries"]:
    print(country["code"], country["name"])

const BASE = "https://dashboard.proxio.net/api/v1"
const API_KEY = "pxo_9fJ2kQ7xR4mN8pL1dW6vB3cH5tZ0aYqS7dK2mN9x"

const res = await fetch(`${BASE}/locations`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
})
const { data } = await res.json()
for (const country of data.countries) console.log(country.code, country.name)

200 response:

{
  "data": {
    "countries": [
      {
        "code": "us",
        "name": "United States",
        "states": [
          {
            "code": "ny",
            "name": "New York",
            "cities": [{ "code": "newyork", "name": "New York" }]
          }
        ]
      }
    ]
  },
  "meta": { "request_id": "req_8Ke2jP4mQ" }
}

Codes are ready to drop straight into targeting: code values are ISO 3166-1 alpha-2 (country), ISO 3166-2 (state), and a dash-free slug (city), all lowercase.

Fetch one country

Pass ?country=us to get just that country's subtree, a much smaller payload when you only need one country's states and cities.

curl "https://dashboard.proxio.net/api/v1/locations?country=us" \
  -H "Authorization: Bearer pxo_9fJ2kQ7xR4mN8pL1dW6vB3cH5tZ0aYqS7dK2mN9x"

Caching

The catalog changes rarely, so responses set Cache-Control: private, max-age=3600. Cache it for up to an hour rather than fetching it on every request. It's private, not public, on purpose: the response is still behind your API key, and public would tell a shared cache sitting in front of your own infrastructure that it's allowed to serve your copy to a different key, Vary: Authorization reinforces that for any cache that stores it anyway.

Every response also carries an ETag, a weak validator over the catalog body. Send it back on your next request as If-None-Match and, if nothing changed, you get 304 Not Modified with no body instead of re-downloading the whole catalog:

# First request, capture the ETag:
curl -si https://dashboard.proxio.net/api/v1/locations \
  -H "Authorization: Bearer pxo_9fJ2kQ7xR4mN8pL1dW6vB3cH5tZ0aYqS7dK2mN9x" \
  | grep -i etag
# ETag: W/"c2FsdGVkX1+3Qz..."

# Next request, conditional:
curl -si https://dashboard.proxio.net/api/v1/locations \
  -H "Authorization: Bearer pxo_9fJ2kQ7xR4mN8pL1dW6vB3cH5tZ0aYqS7dK2mN9x" \
  -H 'If-None-Match: W/"c2FsdGVkX1+3Qz..."'
# HTTP/1.1 304 Not Modified

A 304 carries the same Cache-Control, Vary, and ETag headers the 200 would have, but no data, cheaper than a full fetch for a poller that already has a copy and just wants to know whether it's stale.

Related pages