API Documentation - ATProto PDS Network Map

PDS Location Search

GET /api/pds/search

Search for Personal Data Servers by location, proximity, IP address, or geographic coordinates. Returns a list of PDSs with distance calculations, geolocation data, and server information.

Query Parameters

Parameter	Type	Description	Example
lat	number	Latitude for coordinate search	40.7128
lon	number	Longitude for coordinate search	-74.0060
radius	number	Search radius in kilometers	100
ip	string	IP address to geolocate and search nearby	8.8.8.8
city	string	Filter by city name (partial match)	London
country	string	Filter by country name (partial match)	Germany
continent	string	Filter by continent name	Europe
region	string	Filter by state/region name	California
limit	number	Maximum number of results (default: 100)	50
sortBy	string	Sort results by: distance, online, name (default: distance)	distance

Examples

1. Find PDSs near coordinates (New York City)

curl "https://atmap.j4ck.xyz/api/pds/search?lat=40.7128&lon=-74.0060&radius=100&limit=10"

2. Find PDSs by IP address

curl "https://atmap.j4ck.xyz/api/pds/search?ip=8.8.8.8&radius=500"

3. Find PDSs in a specific city

curl "https://atmap.j4ck.xyz/api/pds/search?city=London&limit=20"

4. Find PDSs in a country

curl "https://atmap.j4ck.xyz/api/pds/search?country=Germany"

5. Find PDSs by continent

curl "https://atmap.j4ck.xyz/api/pds/search?continent=Europe&limit=50"

6. Find PDSs near your current location (uses your IP)

curl "https://atmap.j4ck.xyz/api/pds/search?radius=200&limit=25"

7. Pretty print JSON output with jq

curl "https://atmap.j4ck.xyz/api/pds/search?city=Tokyo&limit=5" | jq

8. Extract just hostnames

curl -s "https://atmap.j4ck.xyz/api/pds/search?country=Japan" | jq -r '.results[].hostname'

Response Format

{
  "count": 10,
  "center": {
    "lat": 40.7128,
    "lon": -74.0060
  },
  "results": [
    {
      "hostname": "example.pds.com",
      "version": "0.4.63",
      "online": true,
      "inviteCodeRequired": false,
      "distance": 12.5,
      "geo": {
        "ip": "192.0.2.1",
        "city": "New York",
        "region": "New York",
        "country": "United States",
        "continent": "North America",
        "lat": 40.7589,
        "lon": -73.9851,
        "isp": "Example ISP"
      }
    }
  ]
}

PDS Statistics

GET /api/stats

Get overall statistics about PDSs tracked by the map including total count, online/offline status, and geolocation coverage.

curl "https://atmap.j4ck.xyz/api/stats"

{
  "total": 2847,
  "online": 2234,
  "offline": 613,
  "geolocated": 2847
}

All PDSs

GET /api/pds-list

Retrieve a complete list of all tracked PDSs with geolocation data, version information, and online status.

curl "https://atmap.j4ck.xyz/api/pds-list" | jq

Get only online PDSs

curl -s "https://atmap.j4ck.xyz/api/pds-list" | jq '[.[] | select(.online == true)]'

PDSs by Country

GET /api/pds-by-country

Get aggregated PDS counts grouped by country with geographic coordinates for visualization.

curl "https://atmap.j4ck.xyz/api/pds-by-country" | jq

[
  {
    "country": "United States",
    "count": 1247,
    "lat": 37.0902,
    "lon": -95.7129
  },
  {
    "country": "Germany",
    "count": 423,
    "lat": 51.1657,
    "lon": 10.4515
  }
]

Historical Stats

GET /api/stats/history

Get historical PDS network statistics tracked daily. Returns total PDSs, online/offline counts, and regional breakdowns by continent and country. Data is logged daily at midnight UK time.

Query Parameters

Parameter	Type	Description	Example
days	number	Get stats for the last N days	30
start	string	Start date (YYYY-MM-DD)	2025-01-01
end	string	End date (YYYY-MM-DD)	2025-01-31

Get all historical data

curl "https://atmap.j4ck.xyz/api/stats/history" | jq

Get last 30 days

curl "https://atmap.j4ck.xyz/api/stats/history?days=30" | jq

Get specific date range

curl "https://atmap.j4ck.xyz/api/stats/history?start=2025-01-01&end=2025-01-31" | jq

[
  {
    "date": "2025-01-15",
    "timestamp": "2025-01-15T00:00:00.000Z",
    "total": 2847,
    "online": 2234,
    "offline": 613,
    "geolocated": 2847,
    "byContinent": {
      "North America": { "total": 1450, "online": 1150 },
      "Europe": { "total": 980, "online": 820 },
      "Asia": { "total": 230, "online": 180 }
    },
    "byCountry": {
      "US": { "country": "United States", "total": 1247, "online": 1000 },
      "DE": { "country": "Germany", "total": 423, "online": 350 }
    }
  }
]

Regional Historical Stats

GET /api/stats/history/region/:region

Get historical statistics for a specific region (continent or country) over time.

Query Parameters

Parameter	Type	Description	Example
type	string	Region type: "continent" or "country"	continent

Get history for Europe (continent)

curl "https://atmap.j4ck.xyz/api/stats/history/region/Europe?type=continent" | jq

Get history for United States (country by code)

curl "https://atmap.j4ck.xyz/api/stats/history/region/US?type=country" | jq

[
  {
    "date": "2025-01-15",
    "timestamp": "2025-01-15T00:00:00.000Z",
    "total": 980,
    "online": 820
  },
  {
    "date": "2025-01-16",
    "timestamp": "2025-01-16T00:00:00.000Z",
    "total": 985,
    "online": 825
  }
]

Health Check

GET /api/health

Check server health and uptime information.

curl "https://atmap.j4ck.xyz/api/health"

{
  "status": "ok",
  "uptime": 86400,
  "timestamp": "2025-11-02T12:00:00.000Z"
}

Rate Limits & Best Practices

General API Endpoints (stats, pds-list, pds-by-country, health, history):
• 200 requests per 15 minutes per IP
• Resets every 15 minutes
• Rate limit headers included in all responses

Search API Endpoint (/api/pds/search):
• 60 requests per 15 minutes per IP
• More restrictive due to computational overhead
• Consider caching results if making repeated searches

Developer Tips:
• Check RateLimit-Remaining header to track usage
• Cache responses when possible to reduce requests
• Use query parameters to narrow results instead of filtering client-side
• For bulk data needs, use /api/pds-list once and filter locally
• Historical data updates once daily - no need to poll frequently

Usage Rights:
• No authentication required
• Free to use for personal and commercial projects
• CORS enabled for browser-based applications
• All responses are JSON formatted
• Feel free to build apps, dashboards, or integrations!

Checking your rate limit status

curl -I "https://atmap.j4ck.xyz/api/stats"

# Response headers include:
# RateLimit-Limit: 200
# RateLimit-Remaining: 195
# RateLimit-Reset: 1699564800