Developers & internal tools

Build a supplier directory

Before you call a supplier overseas, you want to know whether it is the middle of their night. Store two letters for a supplier’s country and look up the rest: the capital, the local time, the calling code, the currency and how a postal code is written.

Try it: change the country in Add a supplier and watch the record fill in. Select a supplier to see what is stored and what is looked up.

Procurement / directory

Suppliers

Six fictional businesses. Real reference data. The local times are live.

Add a supplier

From the country’s record
Codes
US / USA
Capital
Washington, D.C.
Calling code
+1
Currency
USD $ United States dollar
Local time
America/New_York
Postal codes
#####-####

United States America/New_York +1 202 555 0142 USD English
United Kingdom Europe/London +44 1632 960148 GBP English
France Europe/Paris +33 1 99 00 42 16 EUR French
Japan Asia/Tokyo +81 3 0000 1428 JPY Japanese
Australia Australia/Sydney +61 2 5550 0146 AUD English
Germany Europe/Berlin +49 30 0000 1420 EUR German

Between 9 am and 5 pm on a weekday there Outside those hours

Make it your own

Build your own version.

The whole idea is one rule: store the code, look up the rest. A supplier row holds a two-letter country code. Everything else on the screen comes from that country’s record, so it is never typed twice and never goes out of date in your table.

What you store

{
  "name": "Kiso Print Studio",
  "country": "JP",
  "language": "ja",
  "postalCode": "399-5301",
  "phone": "3 0000 1428"
}

What the country record adds

countries.find(c => c.CountryAlpha2 === "JP")

CountryName       Japan
Capital           Tokyo
Continent         Asia
TimeZone          Asia/Tokyo
PhoneCode         +81
CurrencyCode      JPY (Japanese yen)
PostalCodeFormat  ###-####
Tld               .jp

Three steps to a useful form

  1. Load the two lists once

    Countries and Languages are complete and free, with no API key. Fetch each list once on your server and cache it. Do not request them on every keystroke.

    JavaScript
    const load = async list => {
      const r = await fetch(`https://mysafeinfo.com/api/data/${list}?format=json`);
      if (!r.ok) throw new Error(`HTTP ${r.status}`);
      return r.json();
    };
    const [countries, languages] = await Promise.all([load("countries"), load("languages")]);
    C#
    using System.Net.Http.Json;
    using System.Text.Json;
    using var http = new HttpClient();
    var countries = await http.GetFromJsonAsync<JsonElement>("https://mysafeinfo.com/api/data/countries?format=json");
    var languages = await http.GetFromJsonAsync<JsonElement>("https://mysafeinfo.com/api/data/languages?format=json");
    Python
    import json
    from urllib.request import urlopen
    def load(name):
        with urlopen(f"https://mysafeinfo.com/api/data/{name}?format=json", timeout=20) as response:
            return json.load(response)
    countries, languages = load("countries"), load("languages")
  2. Let the country fill in the form

    When someone picks a country, show its calling code, currency and postal code format, check the postal code against PostalCodeRegex, and work out the local time from TimeZone. This is the picker behind the example above.

    // countries and languages are the two complete reference arrays, loaded once (step 1).
    // HTML this expects:
    //   <input id="country" list="countries"><datalist id="countries"></datalist>
    //   <input id="postal-code"><small id="postal-hint"></small>
    //   <select id="language"></select>
    //   <output id="calling-code"></output> <output id="currency"></output> <output id="local-time"></output>
    const countryInput = document.querySelector('#country');
    const postalInput = document.querySelector('#postal-code');
    const languageSelect = document.querySelector('#language');
    const show = (id, text) => { document.querySelector(id).textContent = text; };
    
    for (const country of countries) {
      const option = document.createElement('option');
      option.value = country.CountryName;
      document.querySelector('#countries').append(option);
    }
    for (const language of languages) {
      // Alpha3, because two languages can share an Alpha2 code and one has none.
      languageSelect.add(new Option(language.Language, language.Alpha3));
    }
    
    const chosen = () => countries.find(row => row.CountryName === countryInput.value);
    
    function fillIn() {
      const country = chosen();
      // An unfinished or unrecognized name must not keep the previous country's values.
      show('#calling-code', country?.PhoneCode || '');
      show('#currency', country ? `${country.CurrencyCode} ${country.CurrencyName}` : '');
      // TimeZone is an IANA name such as Asia/Tokyo. The browser works out the time there.
      show('#local-time', country?.TimeZone
        ? new Intl.DateTimeFormat('en', { timeZone: country.TimeZone, weekday: 'short', hour: 'numeric', minute: '2-digit' }).format(new Date())
        : '');
      checkPostalCode();
    }
    
    function checkPostalCode() {
      const country = chosen();
      // About sixty countries have no postal codes: their pattern is blank, so there is nothing to check.
      if (!country?.PostalCodeRegex || !postalInput.value.trim()) return show('#postal-hint', country?.PostalCodeFormat || '');
      const matches = new RegExp(country.PostalCodeRegex, 'i').test(postalInput.value.trim());
      show('#postal-hint', matches ? 'Looks right.' : `Expected ${country.PostalCodeFormat}`);
    }
    
    countryInput.addEventListener('input', fillIn);
    postalInput.addEventListener('input', checkPostalCode);
    
    // When saving, store only codes and the supplier's own details:
    //   { name, country: country.CountryAlpha2, language: languageSelect.value, postalCode, phone }
    // Validate them again on your server, and never infer a person's language from their country.
    
  3. Clean up the records you already have

    Use Country codes to turn names and aliases into codes, then Join CSV files to attach the reference fields. Flag an ambiguous country for review instead of guessing, and validate on the server as well as in the form.

Data notes

A country does not tell you a person’s language. LanguageCodes lists the languages in use in a country, most used first. The example offers them as shortcuts and leaves the choice to the person.

The time zone is the capital’s. A country with several zones, such as the United States or Russia, gets the one its capital is in. Store a supplier’s own zone if you need the exact time in another city.

Postal patterns check the shape, not the address. A code can match and still not exist. About sixty countries and territories have no postal codes, and their format is blank.

Capitals of the 195 sovereign countries follow our World capitals dataset. Postal formats, internet domains, languages and neighbours are from GeoNames (opens in a new tab) (CC BY 4.0), and time zones from the IANA time zone database (opens in a new tab). Check payment and dialing rules with the systems that use them.

The complete Languages list is free too: CSV, JSON or XML. The example stays on this page and does not send a supplier anywhere.

Language reference fields

FieldHow to read it
LanguageLanguage display name.
FamilyLanguage-family grouping recorded in this dataset.
Alpha2Two- or three-letter language code.
Alpha3Two- or three-letter language code.
Alpha3BibliographicA field retained from the source dataset; see its source notes for scope.
ScopeA field retained from the source dataset; see its source notes for scope.
NativeNameA field retained from the source dataset; see its source notes for scope.
DefaultScriptCodeA field retained from the source dataset; see its source notes for scope.
DefaultScriptA field retained from the source dataset; see its source notes for scope.

Questions

Do these free requests need an API key?

No. Both lists come back complete without a key. Anonymous rate limits still apply, so cache the lists in your own application.

Should I store the country’s name or its code?

Store the code. Names change and are spelled differently between systems; the two-letter code is what other datasets join on. Keep the value someone originally typed as well if you need it for an audit.

How does the page know the local time?

The browser does the arithmetic. TimeZone holds an IANA name such as Asia/Tokyo, and Intl.DateTimeFormat turns the current moment into the time there, daylight saving included.

Free in full. No Data Pass or API key needed. Opening this guide does not use your API allowance.

What each record contains

Explore the dataset and its sources. These fields are in the complete download.

FieldHow to read it
CountryName Display name; use the codes for stable joins.
CountryAlpha2 Two-letter ISO country code.
CountryAlpha3 Three-letter ISO country code.
CountryNumeric3 Three-digit ISO code; preserve leading zeros.
CurrencyCode Recorded currency code; verify current currency rules for payments.
PhoneCode Recorded international calling code, including its plus sign.
Capital The capital city. Blank for six territories that have none.
Continent Africa, Antarctica, Asia, Europe, North America, Oceania or South America.
TimeZone The IANA time zone of the capital, such as Asia/Tokyo. Give it to your language’s date library to get the local time.
CurrencyName The name of the currency in CurrencyCode.
CurrencySymbol The currency’s symbol, where it has one.
Tld The country’s internet domain, such as .jp.
PostalCodeFormat How a postal code is written: # is a digit, @ a letter, and | separates alternatives. Blank where there are no postal codes.
PostalCodeRegex A regular expression that checks the shape of a postal code. Match it without regard to case.
LanguageCodes ISO 639 codes of the languages in use, most used first. A hint for a form, not a person’s language.
Neighbours Two-letter codes of the countries it shares a land border with.

Working with the download? Convert CSV to JSON, or turn a column into a list with the comma separator.

For your next project

More subjects to build with.

Countries and Languages are free in full. The Data Pass covers the rest of the catalog.

The Data Pass includes complete downloads and API access across the catalog.

Data Pass

$69one payment / 365 days

See what’s included

No account required. No automatic renewal.