The Perl Toolchain Summit 2025 Needs You: You can help 🙏 Learn more

 / 
Data-Tranco-0.003
River stage zero No dependents
/ Data::Tranco

NAME

Data::Tranco - An interface to the Tranco domain list.

VERSION

version 0.003

SYNOPSIS


            

              
              
use Data::Tranco;
# get a random domain from the list
($domain, $rank) = Data::Tranco->random_domain;
# get a random domain from .org
($domain, $rank) = Data::Tranco->random_domain("org");
# get the highest ranking domain
($domain, $rank) = Data::Tranco->top_domain;
# get the highest ranking domain in .co.uk
($domain, $rank) = Data::Tranco->top_domain("co.uk");
# get a sample of 50 domains
@domains = Data::Tranco->sample(50);
# get a sample of 50 domains in .org
@domains = Data::Tranco->top_domains(50, "org");
# get all 1,000,000 domains
@all = Data::Tranco->all;
# get all domains in .org
@all = Data::Tranco->all("org");
# get the top 50 domains in .jp
@domains = Data::Tranco->top_domains(50, "jp");
# get the ranking of perl.org
$rank = Data::Tranco->rank("perl.org");

DESCRIPTION

Data::Tranco provides an interface to the Tranco list of popular domain names.

METHODS

RANDOM DOMAIN


            

              
              
($domain, $rank) = Data::Tranco->random_domain($suffix);

Returns a randomly-selected domain from the list, along with its ranking. If $suffix is specified, then only a domain that ends with that suffix will be returned.

TOP DOMAIN


            

              
              
($domain, $rank) = Data::Tranco->top_domain($suffix);

Returns the highest-ranking domain from the list, along with its ranking. If $suffix is specified, then the highest-ranking domain that ends with that suffix will be returned.

SAMPLE


            

              
              
@domains = Data::Tranco->sample($count, $suffix);

Returns an array containing $count randomly-selected domains. If $suffix is specified, only domains ending with that suffix will be returned.

TOP N DOMAINS


            

              
              
@domains = Net::Tranco->top_domains($count, $suffix);

Returns an array of the highest ranking $count domains. If $suffix is specified, only domains ending with that suffix will be returned. The number of entries in the array may be less than $count if the TLD is small and/or $count is high.

ALL DOMAINS


            

              
              
@domains = Net::Tranco->all($suffix);

Returns an array of all domains. If $suffix is specified, only domains ending with that suffix will be returned, otherwise, you'll get all 1M domains!

DOMAIN RANK


            

              
              
$rank = Net::Tranco->rank($domain);

Returns the ranking of the domain $domain or undef if the domain isn't present in the list.

DATABASE HANDLE


            

              
              
$db = Data::Tranco->get_db;

Returns a DBI object so you can perform your own queries. The database contains a single table called `domains`, which has the `id` and `domain` columns containing the ranking and domain name, respectively.

IMPLEMENTATION

The Tranco list is published as a zip-compressed CSV file. By default, Data::Tranco will automatically download that file, extract the CSV file, and write it to an SQLite database if (a) the file doesn't exist yet or (b) it's more than a day old.

If you want to control this behaviour, you can use the following:

$Data::Tranco::TTL

This is how old the local file can be (in seconds) before it is updated. It is 86400 seconds by default.

$Data::Tranco::STATIC

If you set this value to 1 then Data::Tranco will not update the database, even if it doesn't exist, in which case, all the methods above will fail.

Data::Tranco->update_db

This will cause Data::Tranco to update its database. If it fails it will croak(), so calls to this method should be wrapped in an `eval`.

AUTHOR

Gavin Brown <gavin.brown@icann.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2024 by Internet Corporation for Assigned Names and Numbers (ICANN).

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.