The PoP catalogue.

GET

/v1/pops

const url = 'https://api.opdns.io/v1/pops';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api.opdns.io/v1/pops

Every PoP of this deployment’s fleet inventory that has a location, sorted by id, for the dashboard map. id is the value the top_pops analytics shape reports; name is the label to show (the city); country is ISO 3166-1 alpha-2; lat and lon are WGS 84 degrees. status: active (serving), canary (serving, receives changes first) or planned (not serving yet). Cacheable for five minutes (Cache-Control: public, max-age=300); changes only on deploy. An empty array when the deployment lists no PoP.

Responses

200

PoPs.

application/json

Array<object>

object

required

Short PoP id, as in top_pops rows and log records (pop).

string

name

required

Label to show.

string

city

required

string

country

required

ISO 3166-1 alpha-2.

string

/^[A-Z]{2}$/

lat

required

number

>= -90 <= 90

lon

required

number

>= -180 <= 180

status

required

string

Allowed values: active canary planned

Example

[
  {
    "id": "ams",
    "name": "Amsterdam",
    "city": "Amsterdam",
    "country": "NL",
    "status": "active"
  }
]

429

Rate limited (rate_limited).

application/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

code

required

Stable machine code.

string

Allowed values: bad_request body_too_large bad_if_match unauthenticated invalid_credentials signup_closed invite_required waitlist_unavailable invalid_token token_expired token_used session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict unknown_list too_many_rules validation_failed rate_limited internal node_revoked node_offline node_busy node_timeout node_error result_too_large shape_unsupported node_token_superseded relay_unavailable not_implemented query_timeout query_too_expensive range_too_large too_many_queries second_factor_required invalid_second_factor mfa_enrolment_required mfa_required reauth_required no_second_factor totp_already_enabled totp_not_enabled last_credential passkey_exists passkey_invalid passkeys_unavailable ceremony_invalid account_pending_deletion credential_required deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists invalid_recovery_code profile_not_empty invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports password_too_short password_too_long profile_suspended

detail

string

errors

Array<object>

object

field

required

string

message

required

string

request_id

string

retry_after

Seconds, repeating the Retry-After header (rate limits, offline nodes).

integer

Example

{
  "type": "https://opdns.io/problems/rate_limited",
  "title": "Too Many Requests",
  "status": 429,
  "code": "rate_limited",
  "detail": "too many requests",
  "request_id": "5f2c9a0e7b1d4c38",
  "retry_after": 6
}

Headers

Retry-After

integer