NAME
InternetData::Database - the licensed database downloads
SYNOPSIS
my $db = $client->database;
my $databases = $db->list;
my $id = $databases->[0]{versions}[-1]{id}; # e.g. 'bogon_ip_v1'
my $meta = $db->metadata($id);
my $sums = $db->checksums($id, 'mmdb');
my $url = $db->download_url($id, 'mmdb'); # transfer it yourself
my $bytes = $db->download_bytes('bogon_asn_v1', 'csvgz');
my $written = $db->download($id, 'mmdb', "./$id.mmdb");DESCRIPTION
Every call this API has, reached through "database" in InternetData. Access is granted by contract rather than self-serve, and needs a key carrying the db.download scope.
The downloads are the whole of this API today, so this namespace covers one domain rather than several. It is here because the sibling VPNDetection client spells the same seven calls the same way, and a program holding both should not have to remember which one is flat.
Every method has a _p twin returning a Mojo::Promise, and every method takes a per-call retries option. Failures die with an InternetData::Error.
METHODS
list
my $databases = $client->database->list;An array reference of the database families this organization may see. A licence is held against a family, and each family carries every published version of itself:
{
base => 'bogon_ip', # what a licence is held against
name => 'Bogon IP',
summary => 'IP ranges that cannot legitimately appear on the internet.',
standing => 'licensed', # licensed, expired or unlicensed
license_type => 'standard', # evaluation, standard, redistribute or undef
starts => '2026-09-04T07:49:45.118Z',
expires => undef, # undef when the licence has no end date
versions => [
{
id => 'bogon_ip_v1', # this is what you download
version => 1,
summary => 'IP ranges that cannot legitimately appear on the internet.',
formats => ['csvgz', 'mmdb'],
},
],
}The id every other method takes is $version->{id}, never $family->{base}.
The listing is not the same for everyone
standing reports where your organization stands against a database, so an unlicensed one is listed and you can see that it exists. A private database is different: it was commissioned for a single customer, so it is absent entirely from a listing for anyone else rather than present with an unlicensed standing. Listing it would advertise that customer.
The server decides this per key. So do not reconstruct a catalog from any other source, do not hold one listing and reuse it for a different key, and do not treat what you got as a list of what InternetData publishes. Nothing here is cached for that reason.
metadata($id)
One database's build document: updated, entries, per-format schema, sample and size. Poll it to decide whether today's build is worth fetching, and read $meta->{size}{$format} to size a transfer before starting it.
checksums($id, $format)
The whole digest set for one published file, as a hash reference keyed by algorithm.
downloads(%options)
Your organization's recent download attempts, newest first, refusals included. limit caps the number returned.
download_url($id, $format)
A time-limited URL for one file. The API answers 302 and this returns the Location without following it. The link carries its own authorization and names no credential of yours, so it is safe to hand to another process; it authorizes the START of a transfer, so one already running is not interrupted when it lapses.
download($id, $format, $path)
Streams one file to $path and returns the bytes written. Nothing beyond one chunk is ever held, whatever the database weighs.
The bytes land in a neighboring .part file that is renamed on completion, so a transfer that dies half way leaves nothing behind that reads as a whole database. A body that stops early is raised rather than accepted: the file is never left short and silent.
download_bytes($id, $format)
Downloads one file and returns its bytes.
This holds the entire file in memory, and the catalog spans seven orders of magnitude, from bogon_asn_v1 at 264 bytes to resproxy_ip_14d_v1 at 5.34 GiB. Reach for it at the small end, where the bytes go straight into a parser, and use "download" for anything you have not measured; "metadata" publishes the size per format without transferring anything, which is how you find out which end you are at.
TRANSFERS
download and download_bytes follow the redirect as a second request carrying no credential: the link authorizes itself, so forwarding the API key would hand it to a host with no business holding it - and object storage answers 400 to a presigned GET that also carries an Authorization header, so it would break the download too.
That transfer is issued exactly once. retries covers the API call that hands out the link, not a transfer that may already have moved gigabytes before it failed, and the per-request timeout that bounds an API call is lifted for it.
SEE ALSO
InternetData, InternetData::Error.
LICENSE
MIT. Copyright Mslm Dev.