Extracts a domain into its component parts (node-url wrapper), performs domain inspection functions


This module provides TLD domain extraction and resolution services. It's useful if you need to extract semantically meaningful tokens from a URL.

npm install tldtools
var tldtools = require('tldtools').init();


var tldtools = require('tldtools');
tldtools.init(function() {

The first time tldtools is loaded it will attempt to call out to to retrieve the latest TLD list. This file is parsed, normalised and stored in /.tlds. To override this outbound call and look locally, place your own overriding file in /effective_tld_names.dat

To force a cache refresh of TLD data in your own running application, you must provide a hook which calls tldtools.tldCacheRefresh

Extracts tld, domain and subdomain parts from the provided fqdn (supports FQDNs names and URIs).

Based on John Kurkowski's tldextract python library.

Returns an object keyed by

  • tld - top level domain (com, etc)
  • domain - first subdomain of tld
  • subdomain - prefixing A records for domain/tld
  • url_tokens - node-url meta structure (convenience)
  • inspect.useful() - closure reporting whether domain and tld parsed correctly
  • inspect.getDomain() - string concatenation of domain + tld

example URL that makes no sense :

var tldtools = require('tldtools').init(function() {


{ subdomain: 'wagga.wagga',
  domain: 'funkjazz',
  tld: '',
   { protocol: 'http:',
     slashes: true,
     auth: 'bob:funk',
     host: '',
     port: '1234',
     hostname: '',
     href: '',
     search: '?go=abc&123',
     query: 'go=abc&123',
     pathname: '/' },
  inspect: { useful: [Function], getDomain: [Function] } }

Rebuilds the local in-memory cache from either the remote TLD datasource, or a local copy of effective_tld_names.dat if the local copy exists.

  • onSuccess - success callback function()
  • onFail - failure callback function(errorMessage)

Attempts to perform a whois lookup for the provided fqdn (supprts FQDNs and URI's)

Available options (opts)

  • hostName - whois hostname (default
  • port - whois port (default 43)
  • stream_encoding - return encoding (default 'utf8')
  • onSuccess - request complete callback function(whoisData, fqdn, cbPassthrough)
  • onFail - failure callback function(errorMessage, fqdn, cbPassthrough) failure callback
  • cbPassthrough - any extra passthrough parameters to onSuccess or onFail


        'onSuccess' : function(whoisData, fqdn, cbPassthrough) {
            console.log(fqdn + ' ultimate success!');
        'onFail' : function(errorMessage, fqdn, cbPassthrough) {
            console.log(fqdn + ' WHOIS FAILED');
    'cbPassthrough' : ['some data']