Skip to content
InternetData

List

get/api/v2/database/list

The whole published catalog, with your organization's license beside each entry, so standing says whether a database is yours today (licensed), was (expired), or has never been bought (unlicensed).

Authorization

ApiKeyQueryAuthapikey in query

?apikey=<key>. Convenient in a browser or a curl one-liner, which is how a database is usually fetched; prefer a header elsewhere.

This is the same v2 key as the other two schemes. A v1 credential is a different vocabulary and fails validation here, as it would anywhere.

ApiKeyHeaderAuthX-Api-Key in header

X-Api-Key: <key>. The same v2 key, for clients that do not set a bearer.

BearerAuthbearer token

Authorization: Bearer <key>, with a key from the console. Keys are default-deny: each operation names the scope it needs, and an existing key does not gain an operation until that scope is added to it.

Responses

200application/json

OK

databasesrequiredarray<object>
baserequiredstring

The family, e.g. vpn_ip. What a license is held against.

Example vpn_ip

namerequiredstring

Example VPN IP

summaryrequiredstring

One line on what the newest version contains.

standingrequired"licensed" | "expired" | "unlicensed"

Where your license for a database family stands today. licensed is a live grant, expired one whose term has ended, and unlicensed a database published but never bought.

openrequiredboolean

An Open database: free under CC BY-SA 4.0 (credit InternetData, https://internetdata.io, and share what you build from it under the same license). Every organization holds a standard license to it from the start, which standing and license_type report like any other.

license_typerequired"evaluation" | "standard" | "redistribute" | null

What your license permits you to do with the data. Null when there is no license, which is every family with standing unlicensed.

startsrequiredstring (date-time)
expiresrequiredstring (date-time)

A hard stop. Null when the license has no end date, which is the normal case for a rolling agreement, and when there is no license. A rolling license reports its turnover date in renews_at instead.

renews_atrequiredstring (date-time)

When a rolling license next renews. Null when the license has no defined term, when expires sets a hard stop instead, and when there is no license.

notice_due_atrequiredstring (date-time)

The last day notice of non-renewal can be given for the term ending at renews_at. Null whenever renews_at is, and when the agreement records no notice period.

versionsrequiredarray<object>

Every published version of this family, oldest first. Old versions are frozen rather than migrated, so both stay downloadable.

idrequiredstring

The versioned id. Pass this to download, checksum and metadata.

Example vpn_ip_v1

versionrequiredinteger

Example 1

summaryrequiredstring
formatsrequiredarray<"csvgz" | "mmdb">

The formats this version is BUILT in. Asking for another is a 400, not a gap - the _provider catalogs are keyed by provider id, so no MMDB exists for them.

sample_formatsarray<"csvgz" | "mmdb">

The formats an evaluation sample is published in, if any.

TypeScript type
ts
{
  databases: ({
    base: string;
    name: string;
    summary: string;
    standing: "licensed" | "expired" | "unlicensed";
    open: boolean;
    license_type: "evaluation" | "standard" | "redistribute" | null;
    starts: string | null;
    expires: string | null;
    renews_at: string | null;
    notice_due_at: string | null;
    versions: ({
      id: string;
      version: number;
      summary: string;
      formats: ("csvgz" | "mmdb")[];
      sample_formats?: ("csvgz" | "mmdb")[];
    })[];
  })[];
}
401application/json

Missing, invalid, revoked or expired key; the key lacks the db.download scope; or the key belongs to no active organization. Each answers the same. rc: UNAUTHORIZED.

rcrequiredstring

A machine-readable result code. Deliberately not an enum: a code added later must stay parseable by a client generated today.

TypeScript type
ts
{
  rc: string;
}
403application/json

The request comes from an address outside the key's or its organization's allowed addresses. Change the allowlist or call from an allowed address: the key itself is fine. rc: IP_NOT_ALLOWED.

rcrequiredstring

A machine-readable result code. Deliberately not an enum: a code added later must stay parseable by a client generated today.

TypeScript type
ts
{
  rc: string;
}