---
title: "ASN geographic distribution from Sugra NetAtlas"
method: GET
path: "/api/v1/network/asn/{asn}/geo-distribution"
tags: ["Sugra NetAtlas"]
---

# ASN geographic distribution from Sugra NetAtlas

`GET /api/v1/network/asn/{asn}/geo-distribution`

Derive country distribution by iterating atlas records for prefixes
matching the given ASN.

Semantic note (SNT-P1-10.1, post 2026-05-25): The ``hq_country`` and
``top_countries`` fields reflect **actual usage country** (geofeed >
cloud-region > peering-registry > RIR allocation priority chain), NOT
the RIR allocation country alone. For globally-distributed ASNs (cloud
providers, CDNs), the distribution now spreads across the regions
where prefixes are actually announced (e.g., AWS AS16509 splits
across us-east-1=US, eu-west-1=IE, ap-northeast-1=JP, etc.) rather
than collapsing to a single RIR-alloc country. For traditional ISPs
the distribution is usually unchanged because they announce from
the same country their RIR allocated to. ``hq_country`` is the
dominant (most-common) actual-usage country, not necessarily the
legal headquarters - the name predates the SNT-P1-10 semantic clarification.

Implementation note: the atlas store does not provide a reverse index
(ASN -> prefixes), so we walk the database. For top ASNs (most
prefixes) this is O(N) in the atlas size (~1 M entries). v1.2-A
caches the response keyed by ``(asn, atlas_etag)`` so subsequent
hits within the same atlas build bypass the full walk; the cache
invalidates automatically when the atlas blob ETag rotates (daily
rebuild).

## Path parameters

- `asn` integer, required

## Response `200`

Successful Response

- unknown

## Other responses

- `401` — Missing or invalid `x-api-key` header.
- `422` — Validation Error
- `429` — Daily rate limit exceeded. Check `X-RateLimit-Reset` for the next window.
- `503` — Upstream source is temporarily unavailable. Retry after a short delay.

---

[API](https://skmtc.net/sugra/apis/sugra-api.md) · [All operations](https://skmtc.net/sugra/apis/sugra-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sugra/sugra-api/versions/4e2740743eb4/schema)