nord.api

Interface to the NordVPN web API.

This module contains a single class, Client, which encapsulates all the methods provided by NordVPN.

class nord.api.Client(api_url='https://api.nordvpn.com/')[source]

Interface to the NordVPN web API.

Instances of this class can be used as async context managers to auto-close the session with the Nord API on exit.

Parameters

api_url (str, default: ‘https://api.nordvpn.com’) –

async close()[source]

Close the underlying aiohttp.ClientSession.

async current_ip()[source]

Return our current public IP address, as detected by NordVPN.

async dns_servers()[source]

Return a list of ip addresses of NordVPN DNS servers.

async host_config(host, protocol='tcp')[source]

Return the OpenVPN config file contents for a NordVPN host.

Parameters
  • host (str) – This hostname may be provided either with or without the trailing ‘.nordvpn.com’.

  • protocol (str, 'tcp' or 'udp') –

async host_info()[source]

Return detailed information about all hosts.

Returns

host_info – A map from hostnames to host info dictionaries.

Return type

(dict: str → dict)

async host_load(host=None)[source]

Return the load on a NordVPN host.

Parameters

host (str, optional) – This hostname may be provided either with or without the trailing ‘.nordvpn.com’. If not provided, get the load on all NordVPN hosts.

Returns

load – If ‘host’ was provided, returns the load on the host as a percentage, otherwise returns a map from hostname to percentage load.

Return type

int or (dict: str → int)

async rank_hosts(country_code, max_load=70, ping_timeout=1)[source]

Return hosts ranked by their suitability.

First, all the NordVPN hosts are filtered to get a list of candidates, then the round-trip time is calculated using ‘ping’, then the candidates are sorted according to some scoring function.

The initial filtering is done based on the country where the host is, and the max.

Parameters
  • country_code (str) – 2-letter country code (e.g. US for United States).

  • max_load (int, default: 70) – An integer between 0 and 100. Hosts with a load greater than this are filtered out.

  • ping_timeout (int) – Each host will be pinged for this amount of time. Larger values yield more accurate round-trip times.

Returns

hosts – Fully qualified domain names of valid hosts, sorted by their rank.

Return type

list of str

async valid_credentials(username, password)[source]

Return True if NordVPN accepts the username and password.

Sometimes connecting to the VPN server gives an authentication error even if the correct credentials are given. This function is useful to first verify credentials so as to avoid unecessary reconnection attempts.

Parameters

password (username,) –

nord.api.normalized_hostname(hostname)[source]

Return the fully qualified domain name of a NordVPN host.