README.md

🗺 Territories

A JSON catalogue of countries, cities and everything inbetween, as well as UI to consume the data

Example

• Andorra
  • Andorra la Vella
  • Canillo
  • Encamp
  • ...
• United Arab Emirates
  • ...
• Afghanistan
  • ...
• ...

Data Structure

territories/
├── packages/
|   └── json/
│       ├── keys.json
│       ├── previews.json
│       ├── AD/
│       │   ├── keys.json
│       │   └── previews.json
│       │   
│       ├── AE/
│       │   ├── keys.json
│       │   └── previews.json
│       │   
│       ├── AD/
│       │   ├── keys.json
│       │   └── previews.json
│       │   ...
│       ...   
...

The root keys.json file in the json folder contains an array of all country ISO 3166-2 codes, if you want to just get a list of all countries.

For example:

[
  "AD",
  "AE",
  "AF",
  // ...
]

However, you probably require a bit more than just the ISO 3166-2 key if you want to surface this information in your user interface. Luckily there is also a previews.json file with a bit more information.

For example:

[
  {
    "key": "AD",
    "icon": "https://cdn.rawgit.com/hjnilsson/country-flags/master/svg/ad.svg",
    "name": "Andorra",
    "link": "https://en.wikipedia.org//wiki/ISO_3166-2:AD"
  },
  {
    "key": "AE",
    "icon": "https://cdn.rawgit.com/hjnilsson/country-flags/master/svg/ae.svg",
    "name": "United Arab Emirates",
    "link": "https://en.wikipedia.org//wiki/ISO_3166-2:AE"
  },
  {
    "key": "AF",
    "icon": "https://cdn.rawgit.com/hjnilsson/country-flags/master/svg/af.svg",
    "name": "Afghanistan",
    "link": "https://en.wikipedia.org//wiki/ISO_3166-2:AF"
  },
  // ...
]

Each of the keys above also has a namesake folder in the root json folder. Each of these have their own keys.json and preview.json files following the same structure. Note that subdivision is the umbrella term used by the ISO 3166-2 for the highest territorial unit under country. This can be states, provinces, districts, prefectures, et al.

For example AD/keys.json:

[
  "AD-07",
  "AE-02",
  "AF-03",
  // ...
]

And also AD/previews.json:

[
  {
    "key": "AD-07",
    "name": "Andorra la Vella",
    "icon": "https:////upload.wikimedia.org/wikipedia/commons/thumb/a/a4/Escut_d%27Andorra_la_Vella.svg/23px-Escut_d%27Andorra_la_Vella.svg.png"
  },
  {
    "key": "AD-02",
    "name": "Canillo",
    "icon": "https:////upload.wikimedia.org/wikipedia/commons/thumb/4/4b/Escut_de_Canillo.svg/23px-Escut_de_Canillo.svg.png"
  },
  {
    "key": "AD-03",
    "name": "Encamp",
    "icon": "https:////upload.wikimedia.org/wikipedia/commons/thumb/e/e9/Escut_d%27Encamp.svg/23px-Escut_d%27Encamp.svg.png"
  },
  // ...
]

Sources

Data is aggregated from several sources, most notably:

• ISO 3166-2 data scraped directly from Wikipedia
• Hampus Joakim Nilsson's country-flags is used to get SVG icons for countries.
• Subdivision SVG icons are scraped straight from Wikipedia.
• UN/LOCODE data is intersected with the above to map cities to subdivisions.
• UN/LOCODE data not mapped to a subdivisions is added to the other folder for a country.