Geolocation

The Geolocation dataset is Synthient's IP geolocation database, rebuilt every day and published as one snapshot per UTC day. Each snapshot comes as three files with the same contents: an MMDB database for in-process lookups, a Parquet file, and a gzip-compressed CSV.

What a snapshot contains

A snapshot covers every routed IPv4 and IPv6 network with its location, network ownership, carrier, company, abuse contact, registration, privacy flags, and risk signals. All three files of a day come from the same build, so you can pick the format that suits the job.

Geolocation is export-only. There is no real-time stream, there are no hourly snapshots, and there is no lite variant. The dataset is served over HTTP; the gRPC export RPCs cover the stream feeds only.

Publishing schedule

A day's snapshot is published shortly after that day begins at 00:00 UTC, normally within half an hour. Until then a request for that date answers 404, and latest keeps resolving to the previous day.

A day can be published again when a later build of it replaces the first one. The files, sizes, and checksums of that date then change. Compare the checksum from the metadata endpoint, or send the ETag back as If-None-Match, to find out whether the copy you hold is still current.

Authentication

All endpoints require your API key in the x-api-key header and are served from https://api.synthient.com under /api/v4. The dataset is gated by the GEOLOCATION_FEED scope. Requests count against the same rate limits as the other export endpoints, and a download counts as one export.

curl -G https://api.synthient.com/api/v4/feeds/geolocation/export \
  -H "x-api-key: $SYNTHIENT_API_KEY"

Columns

The Parquet file and the CSV carry the same columns, in the same order. The schema of the metadata endpoint lists every column of a given day with its type, so read it instead of hard-coding types.

Most columns are strings. latitude and longitude are doubles, geoname_id and radius are 32-bit integers, as_changed and geo_changed are dates, and the nine is_* flags are booleans.

A few details to plan for when you parse the files:

• network is a CIDR block such as 203.0.113.0/24. Accept a bare address as a single-address network.
• asn can carry an AS prefix (AS64500). Strip it before you parse the number.
• country_code and continent_code are two-letter codes. region_code is the subdivision part of an ISO 3166-2 code, so country_code plus - plus region_code gives the full code.
• In the CSV, the is_* flags are written as true or false.
• A value that is not known is an empty field in the CSV. This includes the autonomous system columns on networks with no origin AS.
• as_type and user_type are open sets of lowercase labels, such as hosting, cdn, and home_isp for as_type or residential, business, hosting, and cellular for user_type. Keep values you do not recognize.

The MMDB file

The mmdb file is a MaxMind DB with the database type Synthient-Enterprise. It holds both IPv4 and IPv6 networks and opens with any MMDB reader. Look up an address to get the record of the network that contains it.

mmdblookup --file geolocation.mmdb --ip 203.0.113.7

List snapshots

Returns one page of available daily snapshots, newest-first. Pages are capped at 500 rows; pass next_cursor from the response back as cursor to fetch the next page.

curl -G https://api.synthient.com/api/v4/feeds/geolocation/export \
  -H "x-api-key: $SYNTHIENT_API_KEY" \
  --url-query "limit=1"

{
  "stream": "geolocation",
  "feeds": [
    {
      "kind": "daily",
      "date": "2026-11-14",
      "size_bytes": 1128440217,
      "row_count": 25304112,
      "checksum": "8c1f0a4e6b2d49735e8a9c0b1d2f3a4b5c6d7e8f90a1b2c3d4e5f60718293a4b",
      "id": "2026-11-14",
      "created_at": 1794701112,
      "download_path": "/api/v4/feeds/geolocation/export/2026-11-14",
      "formats": [
        {
          "format": "parquet",
          "size_bytes": 1128440217,
          "checksum": "8c1f0a4e6b2d49735e8a9c0b1d2f3a4b5c6d7e8f90a1b2c3d4e5f60718293a4b"
        },
        {
          "format": "csv",
          "size_bytes": 913205774,
          "checksum": "2e7d5c4b3a291807f6e5d4c3b2a1908f7e6d5c4b3a2918070f1e2d3c4b5a6978"
        },
        {
          "format": "mmdb",
          "size_bytes": 1604118392,
          "checksum": "b4a3928170f6e5d4c3b2a1900f1e2d3c4b5a69788796a5b4c3d2e1f00112233a"
        }
      ]
    }
  ],
  "next_cursor": "eyJkIjoiMjAyNi0xMS0xNCIsImgiOjk5fQ.Q2xhM0VtUGxlU2lnbmF0dXJl"
}

Download a snapshot

Returns a 307 redirect to a presigned R2 URL that is valid for 24 hours. The URL is minted per request and expires, so intermediaries must not cache it. Follow the redirect to download the file, and choose the file with format.

# Follow the 307 with -L and write to a file
curl -L -o geolocation.mmdb \
  "https://api.synthient.com/api/v4/feeds/geolocation/export/latest?format=mmdb" \
  -H "x-api-key: $SYNTHIENT_API_KEY"

{
  "type": "https://docs.synthient.com/errors/bad-request",
  "title": "Bad request",
  "status": 400,
  "detail": "unknown format; expected parquet, csv, mmdb or tar.gz",
  "instance": "4f1c2a9e7b3d4e5f8a6b9c0d1e2f3a4b"
}

Snapshot metadata

Returns JSON metadata for one day: the SHA-256 checksum and byte size of the file you ask for, the row count, the column schema, and every file of the day. It returns no file body.

curl -G https://api.synthient.com/api/v4/feeds/geolocation/export/2026-11-14/meta \
  -H "x-api-key: $SYNTHIENT_API_KEY" \
  --url-query "format=mmdb"

{
  "checksum": "b4a3928170f6e5d4c3b2a1900f1e2d3c4b5a69788796a5b4c3d2e1f00112233a",
  "date": 1794614400,
  "format": "mmdb",
  "size": 1604118392,
  "rows": 25304112,
  "schema": {
    "fields": [
      { "name": "network",      "type": "string" },
      { "name": "city",         "type": "string" },
      { "name": "region",       "type": "string" },
      { "name": "region_code",  "type": "string" },
      { "name": "country",      "type": "string" },
      { "name": "country_code", "type": "string" }
    ]
  },
  "stream": "geolocation",
  "kind": "daily",
  "id": "2026-11-14",
  "created_at": 1794701112,
  "formats": [
    {
      "format": "parquet",
      "size_bytes": 1128440217,
      "checksum": "8c1f0a4e6b2d49735e8a9c0b1d2f3a4b5c6d7e8f90a1b2c3d4e5f60718293a4b"
    },
    {
      "format": "csv",
      "size_bytes": 913205774,
      "checksum": "2e7d5c4b3a291807f6e5d4c3b2a1908f7e6d5c4b3a2918070f1e2d3c4b5a6978"
    },
    {
      "format": "mmdb",
      "size_bytes": 1604118392,
      "checksum": "b4a3928170f6e5d4c3b2a1900f1e2d3c4b5a69788796a5b4c3d2e1f00112233a"
    }
  ]
}

Keeping a local MMDB current

Fetch the metadata once a day, download only when the checksum changes, and verify the file before you swap it in. Use a fixed date for both requests so the metadata and the download describe the same snapshot.

BASE=https://api.synthient.com/api/v4/feeds/geolocation/export

# 1. Resolve the newest day and its MMDB checksum
META=$(curl -sG "$BASE/latest/meta" \
  -H "x-api-key: $SYNTHIENT_API_KEY" --url-query "format=mmdb")
DAY=$(echo "$META" | jq -r '.date | strftime("%Y-%m-%d")')
SUM=$(echo "$META" | jq -r '.checksum')

# 2. Download that day and verify it
curl -sL -o geolocation.mmdb.new "$BASE/$DAY?format=mmdb" \
  -H "x-api-key: $SYNTHIENT_API_KEY"
echo "$SUM  geolocation.mmdb.new" | sha256sum --check

# 3. Replace the live file in one step
mv geolocation.mmdb.new geolocation.mmdb

Response codes

Downloads answer with a 307 redirect: follow the Location header to a 24-hour presigned URL. Every other status follows the shared contract. See Errors for the full reference and retry guidance.