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.
Suppliers
Six fictional businesses. Real reference data. The local times are live.
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
-
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") -
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 fromTimeZone. 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. -
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
| Field | How to read it |
|---|---|
Language | Language display name. |
Family | Language-family grouping recorded in this dataset. |
Alpha2 | Two- or three-letter language code. |
Alpha3 | Two- or three-letter language code. |
Alpha3Bibliographic | A field retained from the source dataset; see its source notes for scope. |
Scope | A field retained from the source dataset; see its source notes for scope. |
NativeName | A field retained from the source dataset; see its source notes for scope. |
DefaultScriptCode | A field retained from the source dataset; see its source notes for scope. |
DefaultScript | A 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.
| Field | How 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.