The PoP catalogue.
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/popsEvery PoP of this deployment’s fleet inventory that has a location, sorted by
id, with its live status, for the dashboard map, the landing page’s globe and
the status page. id is the value the top_pops analytics shape reports;
name is the label to show (the city); region is the subdivision code shown
after it when the inventory has one; country is ISO 3166-1 alpha-2; lat and
lon are WGS 84 degrees.
status follows what the PoP’s servers report (each server’s anycast guard,
every 30 seconds and on every change): serving when every server not drained
for maintenance announces our addresses and passes its health checks,
degraded when some do, down when none does or none has been heard from for
5 minutes, planned when the PoP is not in service yet (none of its servers
counts; a planned PoP may list no server yet). How changes roll out across PoPs
is not part of it. A deployment that does not follow its servers’ reports lists
serving or planned only. Who hosts a PoP is not part of it.
health_updated_at is when a server of the PoP was last heard from; servers
lists each server’s own state, unknown when it has not been heard from
lately.
Which PoPs exist and where follows the inventory the deployment reads at start.
Cacheable for 15 seconds (Cache-Control: public, max-age=15). An empty array
when the deployment lists no PoP.
Responses
Section titled “Responses”PoPs.
object
Short PoP id, as in top_pops rows and log records (pop).
Label to show.
ISO 3166-1 alpha-2.
Subdivision code (ISO 3166-2 without the country), when the inventory has one; shown after the city in place of the country.
serving, degraded (some servers out), down (none answering) or planned (not in service yet).
When a server of the PoP was last heard from; absent when none has been.
The PoP’s servers; empty for a PoP without servers yet.
object
announced or withdrawn as last reported within 5 minutes, else unknown.
Whether it passes its own health checks; absent when unknown.
Taken out of service for maintenance.
Its BGP sessions to the upstream network.
object
When its report was last received.
Example
[ { "id": "ams", "name": "Amsterdam", "city": "Amsterdam", "country": "NL", "region": "NJ", "status": "serving", "servers": [ { "name": "pop-ewr-1", "state": "announced" } ] }]Rate limited (rate_limited). For an API token, the organisation’s plan rate is spent until RateLimit-Reset.
object
Stable machine code.
object
Seconds, repeating the Retry-After header (rate limits, offline nodes).
The plan limit a plan_limit problem hit.
object
The plan’s value of the limit.
Where to move to a larger plan.
The scope the API token lacked (insufficient_scope).
Example
{ "type": "https://opdns.io/problems/rate_limited", "title": "Too Many Requests", "status": 429, "code": "rate_limited", "detail": "Too many requests in a short time. Please wait a moment, then try again.", "request_id": "5f2c9a0e7b1d4c38", "retry_after": 6}Headers
Section titled “Headers”On every response to an API token: the organisation’s plan rate, requests per one-minute window (api_requests_per_minute).
On every response to an API token: the requests left to the organisation in the current window.
On every response to an API token: seconds until the current window ends and the count resets.
On every response to an API token: the quota policy, <limit>;w=60.