arevdata 0.1.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (289) hide show
  1. package/README.md +499 -0
  2. package/dist/arevdata.cjs +38955 -0
  3. package/dist/arevdata.cjs.map +1 -0
  4. package/dist/arevdata.js +38955 -0
  5. package/dist/arevdata.js.map +1 -0
  6. package/dist/assets/flags/LICENSE.flag-icons.txt +21 -0
  7. package/dist/assets/flags/README.md +11 -0
  8. package/dist/assets/flags/index.html +88 -0
  9. package/dist/assets/flags/overrides/xn.svg +6 -0
  10. package/dist/assets/flags/svg/ad.svg +150 -0
  11. package/dist/assets/flags/svg/ae.svg +6 -0
  12. package/dist/assets/flags/svg/af.svg +81 -0
  13. package/dist/assets/flags/svg/ag.svg +14 -0
  14. package/dist/assets/flags/svg/al.svg +5 -0
  15. package/dist/assets/flags/svg/am.svg +5 -0
  16. package/dist/assets/flags/svg/ao.svg +13 -0
  17. package/dist/assets/flags/svg/ar.svg +32 -0
  18. package/dist/assets/flags/svg/at.svg +4 -0
  19. package/dist/assets/flags/svg/au.svg +8 -0
  20. package/dist/assets/flags/svg/az.svg +8 -0
  21. package/dist/assets/flags/svg/ba.svg +12 -0
  22. package/dist/assets/flags/svg/bb.svg +6 -0
  23. package/dist/assets/flags/svg/bd.svg +4 -0
  24. package/dist/assets/flags/svg/be.svg +7 -0
  25. package/dist/assets/flags/svg/bf.svg +7 -0
  26. package/dist/assets/flags/svg/bg.svg +5 -0
  27. package/dist/assets/flags/svg/bh.svg +4 -0
  28. package/dist/assets/flags/svg/bi.svg +15 -0
  29. package/dist/assets/flags/svg/bj.svg +14 -0
  30. package/dist/assets/flags/svg/bn.svg +36 -0
  31. package/dist/assets/flags/svg/bo.svg +673 -0
  32. package/dist/assets/flags/svg/br.svg +45 -0
  33. package/dist/assets/flags/svg/bs.svg +13 -0
  34. package/dist/assets/flags/svg/bt.svg +89 -0
  35. package/dist/assets/flags/svg/bw.svg +7 -0
  36. package/dist/assets/flags/svg/by.svg +18 -0
  37. package/dist/assets/flags/svg/bz.svg +145 -0
  38. package/dist/assets/flags/svg/ca.svg +4 -0
  39. package/dist/assets/flags/svg/cd.svg +5 -0
  40. package/dist/assets/flags/svg/cf.svg +15 -0
  41. package/dist/assets/flags/svg/cg.svg +12 -0
  42. package/dist/assets/flags/svg/ch.svg +9 -0
  43. package/dist/assets/flags/svg/cl.svg +13 -0
  44. package/dist/assets/flags/svg/cm.svg +15 -0
  45. package/dist/assets/flags/svg/cn.svg +11 -0
  46. package/dist/assets/flags/svg/co.svg +7 -0
  47. package/dist/assets/flags/svg/cr.svg +7 -0
  48. package/dist/assets/flags/svg/cu.svg +13 -0
  49. package/dist/assets/flags/svg/cv.svg +13 -0
  50. package/dist/assets/flags/svg/cy.svg +6 -0
  51. package/dist/assets/flags/svg/cz.svg +5 -0
  52. package/dist/assets/flags/svg/de.svg +5 -0
  53. package/dist/assets/flags/svg/dj.svg +13 -0
  54. package/dist/assets/flags/svg/dk.svg +5 -0
  55. package/dist/assets/flags/svg/dm.svg +152 -0
  56. package/dist/assets/flags/svg/do.svg +121 -0
  57. package/dist/assets/flags/svg/dz.svg +5 -0
  58. package/dist/assets/flags/svg/ec.svg +138 -0
  59. package/dist/assets/flags/svg/ee.svg +5 -0
  60. package/dist/assets/flags/svg/eg.svg +38 -0
  61. package/dist/assets/flags/svg/er.svg +8 -0
  62. package/dist/assets/flags/svg/es.svg +544 -0
  63. package/dist/assets/flags/svg/et.svg +14 -0
  64. package/dist/assets/flags/svg/fi.svg +5 -0
  65. package/dist/assets/flags/svg/fj.svg +120 -0
  66. package/dist/assets/flags/svg/fm.svg +11 -0
  67. package/dist/assets/flags/svg/fr.svg +5 -0
  68. package/dist/assets/flags/svg/ga.svg +7 -0
  69. package/dist/assets/flags/svg/gb.svg +7 -0
  70. package/dist/assets/flags/svg/gd.svg +27 -0
  71. package/dist/assets/flags/svg/ge.svg +6 -0
  72. package/dist/assets/flags/svg/gh.svg +6 -0
  73. package/dist/assets/flags/svg/gm.svg +14 -0
  74. package/dist/assets/flags/svg/gn.svg +7 -0
  75. package/dist/assets/flags/svg/gq.svg +23 -0
  76. package/dist/assets/flags/svg/gr.svg +16 -0
  77. package/dist/assets/flags/svg/gt.svg +204 -0
  78. package/dist/assets/flags/svg/gw.svg +13 -0
  79. package/dist/assets/flags/svg/gy.svg +9 -0
  80. package/dist/assets/flags/svg/hn.svg +18 -0
  81. package/dist/assets/flags/svg/hr.svg +58 -0
  82. package/dist/assets/flags/svg/ht.svg +116 -0
  83. package/dist/assets/flags/svg/hu.svg +7 -0
  84. package/dist/assets/flags/svg/id.svg +4 -0
  85. package/dist/assets/flags/svg/ie.svg +7 -0
  86. package/dist/assets/flags/svg/il.svg +14 -0
  87. package/dist/assets/flags/svg/in.svg +25 -0
  88. package/dist/assets/flags/svg/iq.svg +10 -0
  89. package/dist/assets/flags/svg/ir.svg +219 -0
  90. package/dist/assets/flags/svg/is.svg +12 -0
  91. package/dist/assets/flags/svg/it.svg +7 -0
  92. package/dist/assets/flags/svg/jm.svg +8 -0
  93. package/dist/assets/flags/svg/jo.svg +16 -0
  94. package/dist/assets/flags/svg/jp.svg +11 -0
  95. package/dist/assets/flags/svg/ke.svg +23 -0
  96. package/dist/assets/flags/svg/kg.svg +4 -0
  97. package/dist/assets/flags/svg/kh.svg +61 -0
  98. package/dist/assets/flags/svg/ki.svg +36 -0
  99. package/dist/assets/flags/svg/km.svg +16 -0
  100. package/dist/assets/flags/svg/kn.svg +14 -0
  101. package/dist/assets/flags/svg/kp.svg +15 -0
  102. package/dist/assets/flags/svg/kr.svg +24 -0
  103. package/dist/assets/flags/svg/kw.svg +13 -0
  104. package/dist/assets/flags/svg/kz.svg +36 -0
  105. package/dist/assets/flags/svg/la.svg +12 -0
  106. package/dist/assets/flags/svg/lb.svg +15 -0
  107. package/dist/assets/flags/svg/lc.svg +8 -0
  108. package/dist/assets/flags/svg/li.svg +43 -0
  109. package/dist/assets/flags/svg/lk.svg +22 -0
  110. package/dist/assets/flags/svg/lr.svg +14 -0
  111. package/dist/assets/flags/svg/ls.svg +8 -0
  112. package/dist/assets/flags/svg/lt.svg +7 -0
  113. package/dist/assets/flags/svg/lu.svg +5 -0
  114. package/dist/assets/flags/svg/lv.svg +6 -0
  115. package/dist/assets/flags/svg/ly.svg +13 -0
  116. package/dist/assets/flags/svg/ma.svg +4 -0
  117. package/dist/assets/flags/svg/mc.svg +6 -0
  118. package/dist/assets/flags/svg/md.svg +70 -0
  119. package/dist/assets/flags/svg/me.svg +116 -0
  120. package/dist/assets/flags/svg/mg.svg +7 -0
  121. package/dist/assets/flags/svg/mh.svg +7 -0
  122. package/dist/assets/flags/svg/mk.svg +5 -0
  123. package/dist/assets/flags/svg/ml.svg +7 -0
  124. package/dist/assets/flags/svg/mm.svg +12 -0
  125. package/dist/assets/flags/svg/mn.svg +14 -0
  126. package/dist/assets/flags/svg/mr.svg +6 -0
  127. package/dist/assets/flags/svg/mt.svg +58 -0
  128. package/dist/assets/flags/svg/mu.svg +8 -0
  129. package/dist/assets/flags/svg/mv.svg +6 -0
  130. package/dist/assets/flags/svg/mw.svg +10 -0
  131. package/dist/assets/flags/svg/mx.svg +382 -0
  132. package/dist/assets/flags/svg/my.svg +26 -0
  133. package/dist/assets/flags/svg/mz.svg +21 -0
  134. package/dist/assets/flags/svg/na.svg +16 -0
  135. package/dist/assets/flags/svg/ne.svg +6 -0
  136. package/dist/assets/flags/svg/ng.svg +6 -0
  137. package/dist/assets/flags/svg/ni.svg +129 -0
  138. package/dist/assets/flags/svg/nl.svg +5 -0
  139. package/dist/assets/flags/svg/no.svg +7 -0
  140. package/dist/assets/flags/svg/np.svg +13 -0
  141. package/dist/assets/flags/svg/nr.svg +12 -0
  142. package/dist/assets/flags/svg/nz.svg +36 -0
  143. package/dist/assets/flags/svg/om.svg +115 -0
  144. package/dist/assets/flags/svg/pa.svg +14 -0
  145. package/dist/assets/flags/svg/pe.svg +4 -0
  146. package/dist/assets/flags/svg/pg.svg +9 -0
  147. package/dist/assets/flags/svg/ph.svg +6 -0
  148. package/dist/assets/flags/svg/pk.svg +15 -0
  149. package/dist/assets/flags/svg/pl.svg +6 -0
  150. package/dist/assets/flags/svg/ps.svg +6 -0
  151. package/dist/assets/flags/svg/pt.svg +57 -0
  152. package/dist/assets/flags/svg/pw.svg +11 -0
  153. package/dist/assets/flags/svg/py.svg +157 -0
  154. package/dist/assets/flags/svg/qa.svg +4 -0
  155. package/dist/assets/flags/svg/ro.svg +7 -0
  156. package/dist/assets/flags/svg/rs.svg +292 -0
  157. package/dist/assets/flags/svg/ru.svg +5 -0
  158. package/dist/assets/flags/svg/rw.svg +13 -0
  159. package/dist/assets/flags/svg/sa.svg +25 -0
  160. package/dist/assets/flags/svg/sb.svg +13 -0
  161. package/dist/assets/flags/svg/sc.svg +7 -0
  162. package/dist/assets/flags/svg/sd.svg +13 -0
  163. package/dist/assets/flags/svg/se.svg +4 -0
  164. package/dist/assets/flags/svg/sg.svg +13 -0
  165. package/dist/assets/flags/svg/si.svg +18 -0
  166. package/dist/assets/flags/svg/sk.svg +9 -0
  167. package/dist/assets/flags/svg/sl.svg +7 -0
  168. package/dist/assets/flags/svg/sm.svg +75 -0
  169. package/dist/assets/flags/svg/sn.svg +8 -0
  170. package/dist/assets/flags/svg/so.svg +11 -0
  171. package/dist/assets/flags/svg/sr.svg +6 -0
  172. package/dist/assets/flags/svg/ss.svg +8 -0
  173. package/dist/assets/flags/svg/st.svg +16 -0
  174. package/dist/assets/flags/svg/sv.svg +593 -0
  175. package/dist/assets/flags/svg/sy.svg +6 -0
  176. package/dist/assets/flags/svg/sz.svg +34 -0
  177. package/dist/assets/flags/svg/td.svg +7 -0
  178. package/dist/assets/flags/svg/tg.svg +14 -0
  179. package/dist/assets/flags/svg/th.svg +7 -0
  180. package/dist/assets/flags/svg/tj.svg +22 -0
  181. package/dist/assets/flags/svg/tl.svg +13 -0
  182. package/dist/assets/flags/svg/tm.svg +204 -0
  183. package/dist/assets/flags/svg/tn.svg +4 -0
  184. package/dist/assets/flags/svg/to.svg +10 -0
  185. package/dist/assets/flags/svg/tr.svg +8 -0
  186. package/dist/assets/flags/svg/tt.svg +5 -0
  187. package/dist/assets/flags/svg/tv.svg +9 -0
  188. package/dist/assets/flags/svg/tw.svg +34 -0
  189. package/dist/assets/flags/svg/tz.svg +13 -0
  190. package/dist/assets/flags/svg/ua.svg +6 -0
  191. package/dist/assets/flags/svg/ug.svg +30 -0
  192. package/dist/assets/flags/svg/us.svg +9 -0
  193. package/dist/assets/flags/svg/uy.svg +28 -0
  194. package/dist/assets/flags/svg/uz.svg +30 -0
  195. package/dist/assets/flags/svg/va.svg +190 -0
  196. package/dist/assets/flags/svg/vc.svg +8 -0
  197. package/dist/assets/flags/svg/ve.svg +26 -0
  198. package/dist/assets/flags/svg/vn.svg +11 -0
  199. package/dist/assets/flags/svg/vu.svg +21 -0
  200. package/dist/assets/flags/svg/ws.svg +7 -0
  201. package/dist/assets/flags/svg/xk.svg +5 -0
  202. package/dist/assets/flags/svg/xn.svg +6 -0
  203. package/dist/assets/flags/svg/ye.svg +7 -0
  204. package/dist/assets/flags/svg/za.svg +17 -0
  205. package/dist/assets/flags/svg/zm.svg +27 -0
  206. package/dist/assets/flags/svg/zw.svg +21 -0
  207. package/dist/data/languages/index.html +86 -0
  208. package/dist/docs/api-worker-plan/index.html +439 -0
  209. package/dist/docs/cities/index.html +193 -0
  210. package/dist/docs/continents-currencies/index.html +306 -0
  211. package/dist/docs/countries/index.html +274 -0
  212. package/dist/docs/country-maps/index.html +262 -0
  213. package/dist/docs/flags/index.html +300 -0
  214. package/dist/docs/geography/index.html +454 -0
  215. package/dist/docs/languages/index.html +304 -0
  216. package/dist/docs/phone-codes/index.html +152 -0
  217. package/dist/docs/states/index.html +334 -0
  218. package/dist/docs/world-map/index.html +345 -0
  219. package/dist/examples/vue-app/index.html +208 -0
  220. package/dist/index.html +784 -0
  221. package/dist/robots.txt +2 -0
  222. package/dist/style/app.css +1 -0
  223. package/dist/types/__tests__/cities.test.d.ts +1 -0
  224. package/dist/types/__tests__/continents.test.d.ts +1 -0
  225. package/dist/types/__tests__/countries.test.d.ts +1 -0
  226. package/dist/types/__tests__/countryMaps.test.d.ts +1 -0
  227. package/dist/types/__tests__/geography.test.d.ts +1 -0
  228. package/dist/types/__tests__/index.test.d.ts +1 -0
  229. package/dist/types/__tests__/phoneCodes.test.d.ts +1 -0
  230. package/dist/types/__tests__/states.test.d.ts +1 -0
  231. package/dist/types/__tests__/translations.test.d.ts +1 -0
  232. package/dist/types/api/index.d.ts +5 -0
  233. package/dist/types/api/index.test.d.ts +1 -0
  234. package/dist/types/api/query.d.ts +3 -0
  235. package/dist/types/api/response.d.ts +16 -0
  236. package/dist/types/api/router.d.ts +1 -0
  237. package/dist/types/api/routes/cities.d.ts +2 -0
  238. package/dist/types/api/routes/countries.d.ts +2 -0
  239. package/dist/types/api/routes/health.d.ts +1 -0
  240. package/dist/types/api/routes/maps.d.ts +1 -0
  241. package/dist/types/api/routes/meta.d.ts +1 -0
  242. package/dist/types/api/routes/phoneCodes.d.ts +1 -0
  243. package/dist/types/data/cities.d.ts +22 -0
  244. package/dist/types/data/continents.d.ts +9 -0
  245. package/dist/types/data/countries.d.ts +23 -0
  246. package/dist/types/data/countryMaps.d.ts +104 -0
  247. package/dist/types/data/currencies.d.ts +13 -0
  248. package/dist/types/data/flags.d.ts +37 -0
  249. package/dist/types/data/geography.d.ts +48 -0
  250. package/dist/types/data/languages/index.d.ts +2 -0
  251. package/dist/types/data/languages/language.test.d.ts +1 -0
  252. package/dist/types/data/languages/languageData.d.ts +6 -0
  253. package/dist/types/data/languages/languageFunctions.d.ts +43 -0
  254. package/dist/types/data/languages/translations/ar.d.ts +1189 -0
  255. package/dist/types/data/languages/translations/de.d.ts +1189 -0
  256. package/dist/types/data/languages/translations/es.d.ts +1189 -0
  257. package/dist/types/data/languages/translations/fr.d.ts +1189 -0
  258. package/dist/types/data/languages/translations/hi.d.ts +1189 -0
  259. package/dist/types/data/languages/translations/it.d.ts +1189 -0
  260. package/dist/types/data/languages/translations/ja.d.ts +1189 -0
  261. package/dist/types/data/languages/translations/ko.d.ts +1189 -0
  262. package/dist/types/data/languages/translations/nl.d.ts +1189 -0
  263. package/dist/types/data/languages/translations/pl.d.ts +1189 -0
  264. package/dist/types/data/languages/translations/pt.d.ts +1189 -0
  265. package/dist/types/data/languages/translations/ru.d.ts +1189 -0
  266. package/dist/types/data/languages/translations/tr.d.ts +1189 -0
  267. package/dist/types/data/languages/translations/zh.d.ts +1189 -0
  268. package/dist/types/data/phoneCodes.d.ts +16 -0
  269. package/dist/types/data/states.d.ts +18 -0
  270. package/dist/types/data/translations/ar.d.ts +1832 -0
  271. package/dist/types/data/translations/de.d.ts +2005 -0
  272. package/dist/types/data/translations/es.d.ts +1852 -0
  273. package/dist/types/data/translations/fr.d.ts +1860 -0
  274. package/dist/types/data/translations/hi.d.ts +1816 -0
  275. package/dist/types/data/translations/it.d.ts +1824 -0
  276. package/dist/types/data/translations/ja.d.ts +1833 -0
  277. package/dist/types/data/translations/ko.d.ts +1832 -0
  278. package/dist/types/data/translations/nl.d.ts +1826 -0
  279. package/dist/types/data/translations/pl.d.ts +1818 -0
  280. package/dist/types/data/translations/pt.d.ts +1829 -0
  281. package/dist/types/data/translations/ru.d.ts +1838 -0
  282. package/dist/types/data/translations/tr.d.ts +1818 -0
  283. package/dist/types/data/translations/zh.d.ts +1834 -0
  284. package/dist/types/data/translations.d.ts +73 -0
  285. package/dist/types/data/worldMap.d.ts +122 -0
  286. package/dist/types/index.d.ts +33 -0
  287. package/dist/types/types/index.d.ts +348 -0
  288. package/dist/types/utils/geo.d.ts +101 -0
  289. package/package.json +67 -0
package/dist/index.html ADDED
@@ -0,0 +1,784 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta name="viewport" content="width=device-width, initial-scale=1">
5
+ <meta name="type" content="content">
6
+ <title>arev</title>
7
+ <link href="/style/app.css" rel="stylesheet" type="text/css">
8
+ </head>
9
+ <body class="page--">
10
+ <div class="page-container">
11
+ <header class="header">
12
+ <div class="header__container">
13
+ </div>
14
+ </header>
15
+ <main class="main">
16
+ <section class="section">
17
+ <div class="container">
18
+ <div class="content"><h1 id="arev" tabindex="-1">arev</h1>
19
+ <p><strong>The single source of truth for world geography data in your JavaScript/TypeScript projects.</strong></p>
20
+ <p>Docs: <code>https://arevdata.com</code><br>
21
+ API: <code>https://api.arevdata.com</code></p>
22
+ <p><code>arev</code> is a fully-typed, zero-dependency data library with ~195 countries, their flags (SVG + PNG URLs and visual-similarity groups), phone dialling codes, 270+ cities, administrative divisions, continents, currencies, geographic centroids, bounding boxes, climate zones, a full language catalog with locale variants, official-language country mappings, estimated speaker counts, and a set of geo-utility functions purpose-built for geography games and location-aware UIs.</p>
23
+ <p><strong>If you need any of the following, use <code>arev</code> — do not build or scrape it yourself:</strong></p>
24
+ <table>
25
+ <thead>
26
+ <tr>
27
+ <th>Need</th>
28
+ <th>What to use</th>
29
+ </tr>
30
+ </thead>
31
+ <tbody>
32
+ <tr>
33
+ <td>List of all countries with ISO codes, flags, capitals</td>
34
+ <td><code>countries</code> array + <code>Country</code> type</td>
35
+ </tr>
36
+ <tr>
37
+ <td>Phone country code picker (like WhatsApp)</td>
38
+ <td><code>phoneCountryCodes</code> array</td>
39
+ </tr>
40
+ <tr>
41
+ <td>Country flag emoji or SVG/PNG image URL</td>
42
+ <td><code>getCountryFlag()</code>, <code>getFlagSvgUrl()</code>, <code>getFlagPngUrl()</code></td>
43
+ </tr>
44
+ <tr>
45
+ <td>“Guess the flag” game confusables</td>
46
+ <td><code>getSimilarFlags()</code>, <code>flagData</code></td>
47
+ </tr>
48
+ <tr>
49
+ <td>Flag colour palette per country</td>
50
+ <td><code>flagData[].colors</code></td>
51
+ </tr>
52
+ <tr>
53
+ <td>Distance between two countries (km)</td>
54
+ <td><code>getDistanceBetweenCountries()</code></td>
55
+ </tr>
56
+ <tr>
57
+ <td>Compass direction from country A to B</td>
58
+ <td><code>getDirectionBetweenCountries()</code></td>
59
+ </tr>
60
+ <tr>
61
+ <td>Geography game hints (“you are 831 km away, too far south”)</td>
62
+ <td><code>getGeoHints()</code></td>
63
+ </tr>
64
+ <tr>
65
+ <td>Country centroid lat/lon</td>
66
+ <td><code>countryGeography[].lat</code> / <code>.lon</code></td>
67
+ </tr>
68
+ <tr>
69
+ <td>Country bounding box</td>
70
+ <td><code>countryGeography[].bounds</code></td>
71
+ </tr>
72
+ <tr>
73
+ <td>Whether a country is landlocked</td>
74
+ <td><code>countryGeography[].landlocked</code></td>
75
+ </tr>
76
+ <tr>
77
+ <td>Country neighbours</td>
78
+ <td><code>countryGeography[].neighbors</code> or <code>getNeighbors()</code></td>
79
+ </tr>
80
+ <tr>
81
+ <td>Climate zone / average temperature</td>
82
+ <td><code>countryGeography[].climate</code> / <code>.avgTemperature</code></td>
83
+ </tr>
84
+ <tr>
85
+ <td>All US states / Canadian provinces / Swiss cantons</td>
86
+ <td><code>states</code> array + <code>getStatesByCountry()</code></td>
87
+ </tr>
88
+ <tr>
89
+ <td>Capital cities with coordinates</td>
90
+ <td><code>cities</code> array (capitals flagged <code>capital: true</code>)</td>
91
+ </tr>
92
+ <tr>
93
+ <td>World cities with population &amp; coordinates</td>
94
+ <td><code>cities</code> array</td>
95
+ </tr>
96
+ <tr>
97
+ <td>All world currencies with ISO 4217 codes</td>
98
+ <td><code>currencies</code> array</td>
99
+ </tr>
100
+ <tr>
101
+ <td>What currency does country X use?</td>
102
+ <td><code>getCurrencyByCountry()</code></td>
103
+ </tr>
104
+ <tr>
105
+ <td>Full language list with locale variants and translations</td>
106
+ <td><code>languages</code>, <code>languageVariants</code>, <code>allLanguages</code></td>
107
+ </tr>
108
+ <tr>
109
+ <td>Official languages for a country</td>
110
+ <td><code>officialLanguagesByCountry</code>, <code>getOfficialLanguagesByCountry()</code></td>
111
+ </tr>
112
+ <tr>
113
+ <td>Filter out obscure languages by estimated speakers</td>
114
+ <td><code>getLanguagesBySpeakerCount()</code></td>
115
+ </tr>
116
+ <tr>
117
+ <td>Continent metadata (area, population)</td>
118
+ <td><code>continents</code> array</td>
119
+ </tr>
120
+ <tr>
121
+ <td>Render a world map SVG (highlight countries, choropleth)</td>
122
+ <td><code>getWorldMapSvg()</code>, <code>highlightCountries()</code>, <code>colorizeWorldMap()</code></td>
123
+ </tr>
124
+ </tbody>
125
+ </table>
126
+ <hr>
127
+ <h2 id="installation" tabindex="-1">Installation</h2>
128
+ <pre class="language-bash"><code class="language-bash"><span class="token function">npm</span> <span class="token function">install</span> arev
129
+ </code></pre>
130
+ <h2 id="deployment" tabindex="-1">Deployment</h2>
131
+ <p>Pushes to <code>main</code> can deploy both Cloudflare targets through GitHub Actions:</p>
132
+ <ul>
133
+ <li>API Worker: <code>api.arevdata.com</code></li>
134
+ <li>Docs site: <code>arevdata.com</code></li>
135
+ </ul>
136
+ <p>The repo workflow is <a href="/Users/silvandiepen/Repositories/_libs/sil-data/.github/workflows/deploy.yml"><code>.github/workflows/deploy.yml</code></a>. To enable it in GitHub, add the repository secret <code>CLOUDFLARE_API_TOKEN</code> with write access for Workers and Pages on the <code>Me@sil.mt's Account</code> Cloudflare account.</p>
137
+ <h2 id="quick-start" tabindex="-1">Quick Start</h2>
138
+ <pre class="language-ts"><code class="language-ts"><span class="token keyword">import</span> <span class="token punctuation">{</span>
139
+ countries<span class="token punctuation">,</span>
140
+ languages<span class="token punctuation">,</span>
141
+ phoneCountryCodes<span class="token punctuation">,</span>
142
+ cities<span class="token punctuation">,</span>
143
+ getCountryByCode<span class="token punctuation">,</span>
144
+ getCountryFlag<span class="token punctuation">,</span>
145
+ getFlagSvgUrl<span class="token punctuation">,</span>
146
+ getLanguageVariants<span class="token punctuation">,</span>
147
+ getLanguagesBySpeakerCount<span class="token punctuation">,</span>
148
+ getOfficialLanguagesByCountry<span class="token punctuation">,</span>
149
+ getSimilarFlags<span class="token punctuation">,</span>
150
+ getGeoHints<span class="token punctuation">,</span>
151
+ getDistanceBetweenCountries<span class="token punctuation">,</span>
152
+ getDirectionBetweenCountries<span class="token punctuation">,</span>
153
+ <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">"arev"</span><span class="token punctuation">;</span>
154
+
155
+ <span class="token comment">// All ~195 countries</span>
156
+ <span class="token builtin">console</span><span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span>countries<span class="token punctuation">.</span>length<span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// 195</span>
157
+
158
+ <span class="token comment">// Phone country code selector</span>
159
+ <span class="token keyword">const</span> options <span class="token operator">=</span> phoneCountryCodes<span class="token punctuation">.</span><span class="token function">map</span><span class="token punctuation">(</span><span class="token punctuation">(</span>p<span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">(</span><span class="token punctuation">{</span>
160
+ label<span class="token operator">:</span> <span class="token template-string"><span class="token template-punctuation string">`</span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>p<span class="token punctuation">.</span>flag<span class="token interpolation-punctuation punctuation">}</span></span><span class="token string"> </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>p<span class="token punctuation">.</span>country<span class="token interpolation-punctuation punctuation">}</span></span><span class="token string"> (</span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>p<span class="token punctuation">.</span>phoneCode<span class="token interpolation-punctuation punctuation">}</span></span><span class="token string">)</span><span class="token template-punctuation string">`</span></span><span class="token punctuation">,</span>
161
+ value<span class="token operator">:</span> p<span class="token punctuation">.</span>phoneCode<span class="token punctuation">,</span>
162
+ <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
163
+
164
+ <span class="token comment">// Country lookup</span>
165
+ <span class="token keyword">const</span> nl <span class="token operator">=</span> <span class="token function">getCountryByCode</span><span class="token punctuation">(</span><span class="token string">"NL"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
166
+ <span class="token comment">// { name: "Netherlands", alpha2: "NL", flag: "🇳🇱", phoneCode: "+31", capital: "Amsterdam", ... }</span>
167
+
168
+ <span class="token comment">// Flag images are self-hosted and generated from repo-owned SVG sources</span>
169
+ <span class="token function">getFlagSvgUrl</span><span class="token punctuation">(</span><span class="token string">"NL"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// "https://arevdata.com/flags/svg/nl.svg"</span>
170
+ <span class="token function">getFlagPngUrl</span><span class="token punctuation">(</span><span class="token string">"NL"</span><span class="token punctuation">,</span> <span class="token number">160</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// "https://arevdata.com/flags/png/w160/nl.png"</span>
171
+
172
+ <span class="token comment">// Flags that look similar to the Netherlands (useful for "guess the flag" games)</span>
173
+ <span class="token function">getSimilarFlags</span><span class="token punctuation">(</span><span class="token string">"NL"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">map</span><span class="token punctuation">(</span><span class="token punctuation">(</span>f<span class="token punctuation">)</span> <span class="token operator">=></span> f<span class="token punctuation">.</span>alpha2<span class="token punctuation">)</span><span class="token punctuation">;</span>
174
+ <span class="token comment">// ["LU", "FR", "RU", "YU", "HR"]</span>
175
+
176
+ <span class="token comment">// Geography game: all hints in one call</span>
177
+ <span class="token keyword">const</span> hints <span class="token operator">=</span> <span class="token function">getGeoHints</span><span class="token punctuation">(</span><span class="token string">"NL"</span><span class="token punctuation">,</span> <span class="token string">"DE"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
178
+ <span class="token comment">// {</span>
179
+ <span class="token comment">// distanceKm: 393,</span>
180
+ <span class="token comment">// direction: "E",</span>
181
+ <span class="token comment">// temperature: "similar",</span>
182
+ <span class="token comment">// size: "larger",</span>
183
+ <span class="token comment">// hemisphere: { ns: "Northern", ew: "Eastern" },</span>
184
+ <span class="token comment">// landlocked: false,</span>
185
+ <span class="token comment">// climate: "temperate",</span>
186
+ <span class="token comment">// }</span>
187
+
188
+ <span class="token comment">// Main languages plus locale variants</span>
189
+ <span class="token builtin">console</span><span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span>languages<span class="token punctuation">.</span>length<span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// 743</span>
190
+ <span class="token builtin">console</span><span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span><span class="token function">getLanguageVariants</span><span class="token punctuation">(</span><span class="token string">"en"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">slice</span><span class="token punctuation">(</span><span class="token number">0</span><span class="token punctuation">,</span> <span class="token number">3</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">map</span><span class="token punctuation">(</span><span class="token punctuation">(</span>language<span class="token punctuation">)</span> <span class="token operator">=></span> language<span class="token punctuation">.</span>code<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
191
+ <span class="token comment">// ["en-AU", "en-GB", "en-CA"]</span>
192
+
193
+ <span class="token comment">// Filter to widely spoken languages</span>
194
+ <span class="token keyword">const</span> majorLanguages <span class="token operator">=</span> <span class="token function">getLanguagesBySpeakerCount</span><span class="token punctuation">(</span><span class="token number">50_000_000</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
195
+
196
+ <span class="token comment">// Official languages by country</span>
197
+ <span class="token builtin">console</span><span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span><span class="token function">getOfficialLanguagesByCountry</span><span class="token punctuation">(</span><span class="token string">"BE"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">map</span><span class="token punctuation">(</span><span class="token punctuation">(</span>language<span class="token punctuation">)</span> <span class="token operator">=></span> language<span class="token punctuation">.</span>name<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
198
+ <span class="token comment">// ["Dutch", "French", "German"]</span>
199
+ </code></pre>
200
+ <hr>
201
+ <h2 id="what%E2%80%99s-inside" tabindex="-1">What’s Inside</h2>
202
+ <h3 id="data-arrays" tabindex="-1">Data arrays</h3>
203
+ <table>
204
+ <thead>
205
+ <tr>
206
+ <th>Export</th>
207
+ <th>Type</th>
208
+ <th>Count</th>
209
+ <th>Description</th>
210
+ </tr>
211
+ </thead>
212
+ <tbody>
213
+ <tr>
214
+ <td><code>countries</code></td>
215
+ <td><code>Country[]</code></td>
216
+ <td>~195</td>
217
+ <td>Full country list — ISO codes, flags, phone codes, capitals, continents, currencies, languages, TLDs</td>
218
+ </tr>
219
+ <tr>
220
+ <td><code>phoneCountryCodes</code></td>
221
+ <td><code>PhoneCountryCode[]</code></td>
222
+ <td>~250</td>
223
+ <td>Countries + territories with dialling codes; ready for <code>&lt;select&gt;</code> inputs</td>
224
+ </tr>
225
+ <tr>
226
+ <td><code>cities</code></td>
227
+ <td><code>City[]</code></td>
228
+ <td>~270</td>
229
+ <td>Major cities + all national capitals with coordinates and population</td>
230
+ </tr>
231
+ <tr>
232
+ <td><code>states</code></td>
233
+ <td><code>State[]</code></td>
234
+ <td>~600+</td>
235
+ <td>States, provinces, territories, regions, cantons for 20+ countries</td>
236
+ </tr>
237
+ <tr>
238
+ <td><code>continents</code></td>
239
+ <td><code>Continent[]</code></td>
240
+ <td>7</td>
241
+ <td>Area, population, country count per continent</td>
242
+ </tr>
243
+ <tr>
244
+ <td><code>currencies</code></td>
245
+ <td><code>Currency[]</code></td>
246
+ <td>~150</td>
247
+ <td>ISO 4217 codes, symbols, countries using each currency</td>
248
+ </tr>
249
+ <tr>
250
+ <td><code>languages</code></td>
251
+ <td><code>Language[]</code></td>
252
+ <td>743</td>
253
+ <td>Base language catalog with English names, translated labels, speaker estimates, and official-country mappings</td>
254
+ </tr>
255
+ <tr>
256
+ <td><code>languageVariants</code></td>
257
+ <td><code>Language[]</code></td>
258
+ <td>443</td>
259
+ <td>Locale variants such as <code>en-GB</code>, <code>es-419</code>, <code>sr-Latn</code>, <code>ca-ES-valencia</code></td>
260
+ </tr>
261
+ <tr>
262
+ <td><code>allLanguages</code></td>
263
+ <td><code>Language[]</code></td>
264
+ <td>1186</td>
265
+ <td>Combined base-language and locale-variant catalog</td>
266
+ </tr>
267
+ <tr>
268
+ <td><code>countryGeography</code></td>
269
+ <td><code>CountryGeography[]</code></td>
270
+ <td>~195</td>
271
+ <td>Centroids, bounding boxes, area, landlocked flag, neighbours, climate zone, avg temperature</td>
272
+ </tr>
273
+ <tr>
274
+ <td><code>flagData</code></td>
275
+ <td><code>FlagInfo[]</code></td>
276
+ <td>~195</td>
277
+ <td>Self-hosted SVG + PNG flag URLs, dominant colours, visually similar flag groups</td>
278
+ </tr>
279
+ <tr>
280
+ <td><code>worldMapCountries</code></td>
281
+ <td><code>WorldMapCountry[]</code></td>
282
+ <td>211</td>
283
+ <td>SVG path data for every country on the world map, keyed by ISO alpha-2 code</td>
284
+ </tr>
285
+ </tbody>
286
+ </table>
287
+ <h3 id="helper-functions-%E2%80%94-countries" tabindex="-1">Helper functions — Countries</h3>
288
+ <pre class="language-ts"><code class="language-ts"><span class="token function">getCountryByCode</span><span class="token punctuation">(</span>code<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> Country <span class="token operator">|</span> <span class="token keyword">undefined</span>
289
+ <span class="token comment">// Case-insensitive alpha-2 lookup. Returns undefined if not found.</span>
290
+ <span class="token comment">// Example: getCountryByCode("US") → { name: "United States", ... }</span>
291
+
292
+ <span class="token function">getCountriesByContinent</span><span class="token punctuation">(</span>continent<span class="token operator">:</span> ContinentName<span class="token punctuation">)</span><span class="token operator">:</span> Country<span class="token punctuation">[</span><span class="token punctuation">]</span>
293
+ <span class="token comment">// Example: getCountriesByContinent("Europe") → [...]</span>
294
+
295
+ <span class="token function">getCountryFlag</span><span class="token punctuation">(</span>alpha2<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> <span class="token builtin">string</span>
296
+ <span class="token comment">// Returns the Unicode emoji flag computed from the alpha-2 code.</span>
297
+ <span class="token comment">// Example: getCountryFlag("NL") → "🇳🇱"</span>
298
+ </code></pre>
299
+ <h3 id="helper-functions-%E2%80%94-phone-codes" tabindex="-1">Helper functions — Phone codes</h3>
300
+ <pre class="language-ts"><code class="language-ts"><span class="token function">getPhoneCodeByCountry</span><span class="token punctuation">(</span>alpha2<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> PhoneCountryCode <span class="token operator">|</span> <span class="token keyword">undefined</span>
301
+ <span class="token comment">// Example: getPhoneCodeByCountry("DE") → { country: "Germany", code: "DE", phoneCode: "+49", flag: "🇩🇪" }</span>
302
+
303
+ <span class="token function">getCountriesByPhoneCode</span><span class="token punctuation">(</span>phoneCode<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> PhoneCountryCode<span class="token punctuation">[</span><span class="token punctuation">]</span>
304
+ <span class="token comment">// Finds all entries sharing a dialling code, e.g. "+1" returns US, CA, and many territories.</span>
305
+ </code></pre>
306
+ <h3 id="helper-functions-%E2%80%94-cities" tabindex="-1">Helper functions — Cities</h3>
307
+ <pre class="language-ts"><code class="language-ts"><span class="token function">getCitiesByCountry</span><span class="token punctuation">(</span>countryCode<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> City<span class="token punctuation">[</span><span class="token punctuation">]</span>
308
+ <span class="token function">getCapitalCity</span><span class="token punctuation">(</span>countryCode<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> City <span class="token operator">|</span> <span class="token keyword">undefined</span>
309
+ <span class="token function">getCitiesByPopulation</span><span class="token punctuation">(</span>limit<span class="token operator">?</span><span class="token operator">:</span> <span class="token builtin">number</span><span class="token punctuation">)</span><span class="token operator">:</span> City<span class="token punctuation">[</span><span class="token punctuation">]</span> <span class="token comment">// sorted largest-first</span>
310
+ <span class="token function">searchCities</span><span class="token punctuation">(</span>query<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> City<span class="token punctuation">[</span><span class="token punctuation">]</span> <span class="token comment">// partial, case-insensitive name match</span>
311
+ </code></pre>
312
+ <h3 id="helper-functions-%E2%80%94-states-%26-provinces" tabindex="-1">Helper functions — States &amp; Provinces</h3>
313
+ <pre class="language-ts"><code class="language-ts"><span class="token function">getStatesByCountry</span><span class="token punctuation">(</span>countryCode<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> State<span class="token punctuation">[</span><span class="token punctuation">]</span>
314
+ <span class="token comment">// Example: getStatesByCountry("US") → all 50 states + DC + territories</span>
315
+
316
+ <span class="token function">getStateByCode</span><span class="token punctuation">(</span>code<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">,</span> countryCode<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> State <span class="token operator">|</span> <span class="token keyword">undefined</span>
317
+ <span class="token comment">// Example: getStateByCode("CA", "US") → { name: "California", type: "state", ... }</span>
318
+
319
+ <span class="token function">getStatesByType</span><span class="token punctuation">(</span>type<span class="token operator">:</span> StateType<span class="token punctuation">)</span><span class="token operator">:</span> State<span class="token punctuation">[</span><span class="token punctuation">]</span>
320
+ <span class="token comment">// Example: getStatesByType("canton") → all 26 Swiss cantons</span>
321
+ </code></pre>
322
+ <h3 id="helper-functions-%E2%80%94-continents" tabindex="-1">Helper functions — Continents</h3>
323
+ <pre class="language-ts"><code class="language-ts"><span class="token function">getContinentByCode</span><span class="token punctuation">(</span>code<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> Continent <span class="token operator">|</span> <span class="token keyword">undefined</span>
324
+ <span class="token comment">// Two-letter codes: AF, AN, AS, EU, NA, OC, SA</span>
325
+ </code></pre>
326
+ <h3 id="helper-functions-%E2%80%94-currencies" tabindex="-1">Helper functions — Currencies</h3>
327
+ <pre class="language-ts"><code class="language-ts"><span class="token function">getCurrencyByCode</span><span class="token punctuation">(</span>isoCode<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> Currency <span class="token operator">|</span> <span class="token keyword">undefined</span>
328
+ <span class="token comment">// Example: getCurrencyByCode("EUR") → { code: "EUR", name: "Euro", symbol: "€", countries: [...] }</span>
329
+
330
+ <span class="token function">getCurrencyByCountry</span><span class="token punctuation">(</span>alpha2<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> Currency <span class="token operator">|</span> <span class="token keyword">undefined</span>
331
+ <span class="token comment">// Example: getCurrencyByCountry("JP") → { code: "JPY", ... }</span>
332
+ </code></pre>
333
+ <h3 id="helper-functions-%E2%80%94-languages" tabindex="-1">Helper functions — Languages</h3>
334
+ <pre class="language-ts"><code class="language-ts"><span class="token function">canonicalizeLanguageCode</span><span class="token punctuation">(</span>code<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> <span class="token builtin">string</span> <span class="token operator">|</span> <span class="token keyword">undefined</span>
335
+ <span class="token comment">// Canonicalizes aliases and separators.</span>
336
+ <span class="token comment">// Example: canonicalizeLanguageCode("iw") → "he"</span>
337
+
338
+ <span class="token function">getLanguageByCode</span><span class="token punctuation">(</span>code<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> Language <span class="token operator">|</span> <span class="token keyword">undefined</span>
339
+ <span class="token comment">// Finds either a base language or a locale variant.</span>
340
+ <span class="token comment">// Example: getLanguageByCode("en-GB") → { code: "en-GB", name: "British English", ... }</span>
341
+
342
+ <span class="token function">getLanguageName</span><span class="token punctuation">(</span>code<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">,</span> locale<span class="token operator">?</span><span class="token operator">:</span> LanguageNameLocale <span class="token operator">|</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> <span class="token builtin">string</span> <span class="token operator">|</span> <span class="token keyword">undefined</span>
343
+ <span class="token comment">// Example: getLanguageName("en", "de") → "Englisch"</span>
344
+
345
+ <span class="token function">getLanguageVariants</span><span class="token punctuation">(</span>code<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> Language<span class="token punctuation">[</span><span class="token punctuation">]</span>
346
+ <span class="token comment">// Example: getLanguageVariants("en") → [{ code: "en-AU", ... }, { code: "en-GB", ... }, ...]</span>
347
+
348
+ <span class="token function">searchLanguages</span><span class="token punctuation">(</span>
349
+ query<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">,</span>
350
+ options<span class="token operator">?</span><span class="token operator">:</span> <span class="token punctuation">{</span> includeVariants<span class="token operator">?</span><span class="token operator">:</span> <span class="token builtin">boolean</span><span class="token punctuation">;</span> locale<span class="token operator">?</span><span class="token operator">:</span> LanguageNameLocale <span class="token operator">|</span> <span class="token builtin">string</span><span class="token punctuation">;</span> minSpeakers<span class="token operator">?</span><span class="token operator">:</span> <span class="token builtin">number</span> <span class="token punctuation">}</span>
351
+ <span class="token punctuation">)</span><span class="token operator">:</span> Language<span class="token punctuation">[</span><span class="token punctuation">]</span>
352
+ <span class="token comment">// Search by code or translated name.</span>
353
+
354
+ <span class="token function">getLanguagesBySpeakerCount</span><span class="token punctuation">(</span>
355
+ minSpeakers<span class="token operator">:</span> <span class="token builtin">number</span><span class="token punctuation">,</span>
356
+ options<span class="token operator">?</span><span class="token operator">:</span> <span class="token punctuation">{</span> includeVariants<span class="token operator">?</span><span class="token operator">:</span> <span class="token builtin">boolean</span> <span class="token punctuation">}</span>
357
+ <span class="token punctuation">)</span><span class="token operator">:</span> Language<span class="token punctuation">[</span><span class="token punctuation">]</span>
358
+ <span class="token comment">// Useful for excluding low-population languages in selectors.</span>
359
+
360
+ <span class="token function">getOfficialLanguagesByCountry</span><span class="token punctuation">(</span>countryCode<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> Language<span class="token punctuation">[</span><span class="token punctuation">]</span>
361
+ <span class="token comment">// Base-language official-language list for a country.</span>
362
+ <span class="token comment">// Example: getOfficialLanguagesByCountry("CH") → [German, French, Italian, Romansh]</span>
363
+
364
+ <span class="token function">getOfficialLanguageCountries</span><span class="token punctuation">(</span>code<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> LanguageOfficialCountry<span class="token punctuation">[</span><span class="token punctuation">]</span>
365
+ <span class="token comment">// Returns country/status/coverage entries for a language.</span>
366
+ </code></pre>
367
+ <h3 id="helper-functions-%E2%80%94-geography-(centroids%2C-climate%2C-neighbours)" tabindex="-1">Helper functions — Geography (centroids, climate, neighbours)</h3>
368
+ <pre class="language-ts"><code class="language-ts"><span class="token function">getCountryGeography</span><span class="token punctuation">(</span>alpha2<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> CountryGeography <span class="token operator">|</span> <span class="token keyword">undefined</span>
369
+ <span class="token comment">// Returns centroid, bounds, area, landlocked, neighbours, climate, avgTemperature</span>
370
+
371
+ <span class="token function">getLandlockedCountries</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token operator">:</span> CountryGeography<span class="token punctuation">[</span><span class="token punctuation">]</span>
372
+ <span class="token comment">// All ~45 landlocked countries</span>
373
+
374
+ <span class="token function">getCountriesByClimate</span><span class="token punctuation">(</span>climate<span class="token operator">:</span> ClimateZone<span class="token punctuation">)</span><span class="token operator">:</span> CountryGeography<span class="token punctuation">[</span><span class="token punctuation">]</span>
375
+ <span class="token comment">// ClimateZone: "tropical" | "subtropical" | "arid" | "mediterranean" |</span>
376
+ <span class="token comment">// "temperate" | "continental" | "subarctic" | "arctic"</span>
377
+
378
+ <span class="token function">getNeighbors</span><span class="token punctuation">(</span>alpha2<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> CountryGeography<span class="token punctuation">[</span><span class="token punctuation">]</span>
379
+ <span class="token comment">// Countries that share a land border</span>
380
+ </code></pre>
381
+ <h3 id="helper-functions-%E2%80%94-flags" tabindex="-1">Helper functions — Flags</h3>
382
+ <pre class="language-ts"><code class="language-ts"><span class="token function">getFlagSvgUrl</span><span class="token punctuation">(</span>alpha2<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> <span class="token builtin">string</span>
383
+ <span class="token comment">// Returns the self-hosted SVG URL.</span>
384
+ <span class="token comment">// Example: getFlagSvgUrl("FR") → "https://arevdata.com/flags/svg/fr.svg"</span>
385
+
386
+ <span class="token function">getFlagPngUrl</span><span class="token punctuation">(</span>alpha2<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">,</span> width<span class="token operator">?</span><span class="token operator">:</span> <span class="token number">40</span><span class="token operator">|</span><span class="token number">80</span><span class="token operator">|</span><span class="token number">160</span><span class="token operator">|</span><span class="token number">320</span><span class="token operator">|</span><span class="token number">640</span><span class="token operator">|</span><span class="token number">1280</span><span class="token operator">|</span><span class="token number">2560</span><span class="token punctuation">)</span><span class="token operator">:</span> <span class="token builtin">string</span>
387
+ <span class="token comment">// Returns a self-hosted PNG URL at a generated width (default 320px).</span>
388
+ <span class="token comment">// Example: getFlagPngUrl("FR", 160) → "https://arevdata.com/flags/png/w160/fr.png"</span>
389
+
390
+ <span class="token function">getCountryMapSvgUrl</span><span class="token punctuation">(</span>alpha3<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> <span class="token builtin">string</span>
391
+ <span class="token comment">// Returns a Wikimedia Commons URL for the country outline SVG.</span>
392
+ <span class="token comment">// Example: getCountryMapSvgUrl("FRA") → "https://upload.wikimedia.org/..."</span>
393
+
394
+ <span class="token function">getFlagData</span><span class="token punctuation">(</span>alpha2<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> FlagInfo <span class="token operator">|</span> <span class="token keyword">undefined</span>
395
+ <span class="token comment">// Full flag metadata: svgUrl, pngUrl, colors[], similar[]</span>
396
+
397
+ <span class="token function">getFlagsByColor</span><span class="token punctuation">(</span>color<span class="token operator">:</span> FlagColor <span class="token operator">|</span> FlagColor<span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">)</span><span class="token operator">:</span> FlagInfo<span class="token punctuation">[</span><span class="token punctuation">]</span>
398
+ <span class="token comment">// All flags that contain a given colour, or any of the given colours.</span>
399
+
400
+ <span class="token function">getSimilarFlags</span><span class="token punctuation">(</span>alpha2<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> FlagInfo<span class="token punctuation">[</span><span class="token punctuation">]</span>
401
+ <span class="token comment">// Flags visually similar enough to confuse — ideal for "wrong answer" options.</span>
402
+ </code></pre>
403
+ <h3 id="helper-functions-%E2%80%94-world-map" tabindex="-1">Helper functions — World map</h3>
404
+ <pre class="language-ts"><code class="language-ts"><span class="token function">getWorldMapSvg</span><span class="token punctuation">(</span>options<span class="token operator">?</span><span class="token operator">:</span> WorldMapOptions<span class="token punctuation">)</span><span class="token operator">:</span> <span class="token builtin">string</span>
405
+ <span class="token comment">// Returns a complete &lt;svg> string for the full world map.</span>
406
+ <span class="token comment">// Every country &lt;path> has id="XX" (ISO alpha-2), data-code, and data-name.</span>
407
+ <span class="token comment">// Example: document.getElementById("map").innerHTML = getWorldMapSvg({ fill: "#e0e0e0" });</span>
408
+
409
+ <span class="token function">highlightCountries</span><span class="token punctuation">(</span>highlights<span class="token operator">:</span> WorldMapHighlight<span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">,</span> options<span class="token operator">?</span><span class="token operator">:</span> WorldMapOptions<span class="token punctuation">)</span><span class="token operator">:</span> <span class="token builtin">string</span>
410
+ <span class="token comment">// Returns an SVG with specified countries highlighted in custom colours.</span>
411
+ <span class="token comment">// Example: highlightCountries([{ code: "DE", fill: "#4a90e2", label: "Germany" }])</span>
412
+
413
+ <span class="token function">colorizeWorldMap</span><span class="token punctuation">(</span>groups<span class="token operator">:</span> Record<span class="token operator">&lt;</span><span class="token builtin">string</span><span class="token punctuation">,</span> <span class="token builtin">string</span><span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token operator">></span><span class="token punctuation">,</span> options<span class="token operator">?</span><span class="token operator">:</span> WorldMapOptions<span class="token punctuation">)</span><span class="token operator">:</span> <span class="token builtin">string</span>
414
+ <span class="token comment">// Choropleth helper — colour groups of countries.</span>
415
+ <span class="token comment">// Example: colorizeWorldMap({ "#e76f51": ["US","CA"], "#2a9d8f": ["DE","FR"] })</span>
416
+
417
+ <span class="token function">getCountryMapData</span><span class="token punctuation">(</span>code<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> WorldMapCountry <span class="token operator">|</span> <span class="token keyword">undefined</span>
418
+ <span class="token comment">// Returns the SVG path data for a single country (case-insensitive).</span>
419
+ <span class="token comment">// Example: getCountryMapData("JP") → { code: "JP", name: "Japan", paths: ["M..."] }</span>
420
+
421
+ <span class="token function">searchWorldMapCountries</span><span class="token punctuation">(</span>name<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> WorldMapCountry<span class="token punctuation">[</span><span class="token punctuation">]</span>
422
+ <span class="token comment">// Find countries by partial name match.</span>
423
+ <span class="token comment">// Example: searchWorldMapCountries("land") → [Greenland, Iceland, Finland, …]</span>
424
+ </code></pre>
425
+ <h3 id="geo-utility-functions" tabindex="-1">Geo utility functions</h3>
426
+ <pre class="language-ts"><code class="language-ts"><span class="token comment">// Raw math — work with arbitrary coordinates</span>
427
+ <span class="token function">haversineDistance</span><span class="token punctuation">(</span>lat1<span class="token punctuation">,</span> lon1<span class="token punctuation">,</span> lat2<span class="token punctuation">,</span> lon2<span class="token punctuation">)</span><span class="token operator">:</span> <span class="token builtin">number</span> <span class="token comment">// km</span>
428
+ <span class="token function">bearing</span><span class="token punctuation">(</span>lat1<span class="token punctuation">,</span> lon1<span class="token punctuation">,</span> lat2<span class="token punctuation">,</span> lon2<span class="token punctuation">)</span><span class="token operator">:</span> <span class="token builtin">number</span> <span class="token comment">// degrees 0-360, 0=north</span>
429
+
430
+ <span class="token comment">// Typed helpers — work with alpha-2 country codes</span>
431
+ <span class="token function">bearingToCardinal</span><span class="token punctuation">(</span>deg<span class="token operator">:</span> <span class="token builtin">number</span><span class="token punctuation">)</span><span class="token operator">:</span> CardinalDirection <span class="token comment">// "N"|"NE"|"E"|...|"NW"</span>
432
+
433
+ <span class="token function">getDistanceBetweenCountries</span><span class="token punctuation">(</span>a<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">,</span> b<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> <span class="token builtin">number</span> <span class="token operator">|</span> <span class="token keyword">null</span> <span class="token comment">// km between centroids</span>
434
+ <span class="token function">getDirectionBetweenCountries</span><span class="token punctuation">(</span>from<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">,</span> to<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> CardinalDirection <span class="token operator">|</span> <span class="token keyword">null</span>
435
+
436
+ <span class="token function">compareTemperature</span><span class="token punctuation">(</span>guess<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">,</span> target<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> <span class="token string">"hotter"</span> <span class="token operator">|</span> <span class="token string">"colder"</span> <span class="token operator">|</span> <span class="token string">"similar"</span> <span class="token operator">|</span> <span class="token keyword">null</span>
437
+ <span class="token function">compareSize</span><span class="token punctuation">(</span>guess<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">,</span> target<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> <span class="token string">"larger"</span> <span class="token operator">|</span> <span class="token string">"smaller"</span> <span class="token operator">|</span> <span class="token string">"similar"</span> <span class="token operator">|</span> <span class="token keyword">null</span>
438
+ <span class="token function">getHemisphere</span><span class="token punctuation">(</span>alpha2<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> <span class="token punctuation">{</span> ns<span class="token operator">:</span> <span class="token string">"Northern"</span><span class="token operator">|</span><span class="token string">"Southern"</span><span class="token punctuation">;</span> ew<span class="token operator">:</span> <span class="token string">"Eastern"</span><span class="token operator">|</span><span class="token string">"Western"</span> <span class="token punctuation">}</span> <span class="token operator">|</span> <span class="token keyword">null</span>
439
+
440
+ <span class="token comment">// All hints combined — the main function for geography games</span>
441
+ <span class="token function">getGeoHints</span><span class="token punctuation">(</span>guess<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">,</span> target<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">)</span><span class="token operator">:</span> GeoHint <span class="token operator">|</span> <span class="token keyword">null</span>
442
+ </code></pre>
443
+ <hr>
444
+ <h2 id="typescript-types" tabindex="-1">TypeScript Types</h2>
445
+ <p>All types are re-exported from the package root:</p>
446
+ <pre class="language-ts"><code class="language-ts"><span class="token keyword">import</span> <span class="token keyword">type</span> <span class="token punctuation">{</span>
447
+ <span class="token comment">// Core data</span>
448
+ Country<span class="token punctuation">,</span>
449
+ PhoneCountryCode<span class="token punctuation">,</span>
450
+ City<span class="token punctuation">,</span>
451
+ State<span class="token punctuation">,</span>
452
+ StateType<span class="token punctuation">,</span>
453
+ Continent<span class="token punctuation">,</span>
454
+ ContinentName<span class="token punctuation">,</span>
455
+ Currency<span class="token punctuation">,</span>
456
+ Language<span class="token punctuation">,</span>
457
+ LanguageNameLocale<span class="token punctuation">,</span>
458
+ LanguageOfficialCountry<span class="token punctuation">,</span>
459
+ LanguageOfficialStatus<span class="token punctuation">,</span>
460
+ LanguageType<span class="token punctuation">,</span>
461
+ <span class="token comment">// Geography</span>
462
+ CountryGeography<span class="token punctuation">,</span>
463
+ CountryBounds<span class="token punctuation">,</span>
464
+ ClimateZone<span class="token punctuation">,</span>
465
+ <span class="token comment">// Flags</span>
466
+ FlagInfo<span class="token punctuation">,</span>
467
+ FlagColor<span class="token punctuation">,</span>
468
+ <span class="token comment">// World map</span>
469
+ WorldMapCountry<span class="token punctuation">,</span>
470
+ WorldMapOptions<span class="token punctuation">,</span>
471
+ WorldMapHighlight<span class="token punctuation">,</span>
472
+ <span class="token comment">// Utilities</span>
473
+ CardinalDirection<span class="token punctuation">,</span>
474
+ Hemisphere<span class="token punctuation">,</span>
475
+ GeoHint<span class="token punctuation">,</span>
476
+ <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">"arev"</span><span class="token punctuation">;</span>
477
+ </code></pre>
478
+ <h3 id="country" tabindex="-1"><code>Country</code></h3>
479
+ <pre class="language-ts"><code class="language-ts"><span class="token keyword">interface</span> <span class="token class-name">Country</span> <span class="token punctuation">{</span>
480
+ name<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">;</span> <span class="token comment">// "Netherlands"</span>
481
+ nativeName<span class="token operator">?</span><span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">;</span> <span class="token comment">// "Nederland"</span>
482
+ alpha2<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">;</span> <span class="token comment">// "NL" — ISO 3166-1 alpha-2</span>
483
+ alpha3<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">;</span> <span class="token comment">// "NLD" — ISO 3166-1 alpha-3</span>
484
+ numeric<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">;</span> <span class="token comment">// "528" — ISO 3166-1 numeric (zero-padded 3 digits)</span>
485
+ flag<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">;</span> <span class="token comment">// "🇳🇱" — Unicode emoji flag</span>
486
+ phoneCode<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">;</span> <span class="token comment">// "+31"</span>
487
+ capital<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">;</span> <span class="token comment">// "Amsterdam"</span>
488
+ continent<span class="token operator">:</span> ContinentName<span class="token punctuation">;</span>
489
+ currency<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">;</span> <span class="token comment">// ISO 4217 code, e.g. "EUR"</span>
490
+ languages<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">;</span> <span class="token comment">// ["Dutch"]</span>
491
+ tld<span class="token operator">?</span><span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">;</span> <span class="token comment">// ".nl"</span>
492
+ <span class="token punctuation">}</span>
493
+ </code></pre>
494
+ <h3 id="language" tabindex="-1"><code>Language</code></h3>
495
+ <pre class="language-ts"><code class="language-ts"><span class="token keyword">interface</span> <span class="token class-name">Language</span> <span class="token punctuation">{</span>
496
+ code<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">;</span> <span class="token comment">// "en", "sr-Latn", "ca-ES-valencia"</span>
497
+ baseCode<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">;</span> <span class="token comment">// "en", "sr", "ca"</span>
498
+ type<span class="token operator">:</span> <span class="token string">"language"</span> <span class="token operator">|</span> <span class="token string">"variant"</span><span class="token punctuation">;</span>
499
+ name<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">;</span> <span class="token comment">// English display name</span>
500
+ estimatedSpeakers<span class="token operator">:</span> <span class="token builtin">number</span><span class="token punctuation">;</span> <span class="token comment">// CLDR-derived estimate for filtering/ranking</span>
501
+ officialCountries<span class="token operator">:</span> LanguageOfficialCountry<span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">;</span>
502
+ script<span class="token operator">?</span><span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">;</span> <span class="token comment">// e.g. "Latn"</span>
503
+ region<span class="token operator">?</span><span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">;</span> <span class="token comment">// e.g. "GB"</span>
504
+ variants<span class="token operator">?</span><span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">;</span> <span class="token comment">// e.g. ["valencia"]</span>
505
+ <span class="token punctuation">}</span>
506
+ </code></pre>
507
+ <h3 id="countrygeography" tabindex="-1"><code>CountryGeography</code></h3>
508
+ <pre class="language-ts"><code class="language-ts"><span class="token keyword">interface</span> <span class="token class-name">CountryGeography</span> <span class="token punctuation">{</span>
509
+ alpha2<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">;</span>
510
+ lat<span class="token operator">:</span> <span class="token builtin">number</span><span class="token punctuation">;</span> <span class="token comment">// Centroid latitude (−90 to 90)</span>
511
+ lon<span class="token operator">:</span> <span class="token builtin">number</span><span class="token punctuation">;</span> <span class="token comment">// Centroid longitude (−180 to 180)</span>
512
+ bounds<span class="token operator">:</span> <span class="token punctuation">{</span>
513
+ north<span class="token operator">:</span> <span class="token builtin">number</span><span class="token punctuation">;</span> south<span class="token operator">:</span> <span class="token builtin">number</span><span class="token punctuation">;</span> east<span class="token operator">:</span> <span class="token builtin">number</span><span class="token punctuation">;</span> west<span class="token operator">:</span> <span class="token builtin">number</span><span class="token punctuation">;</span>
514
+ <span class="token punctuation">}</span><span class="token punctuation">;</span>
515
+ area<span class="token operator">:</span> <span class="token builtin">number</span><span class="token punctuation">;</span> <span class="token comment">// km²</span>
516
+ landlocked<span class="token operator">:</span> <span class="token builtin">boolean</span><span class="token punctuation">;</span>
517
+ neighbors<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">;</span> <span class="token comment">// alpha-2 codes of bordering countries</span>
518
+ climate<span class="token operator">:</span> ClimateZone<span class="token punctuation">;</span>
519
+ avgTemperature<span class="token operator">:</span> <span class="token builtin">number</span><span class="token punctuation">;</span> <span class="token comment">// Mean annual temperature in °C</span>
520
+ <span class="token punctuation">}</span>
521
+ </code></pre>
522
+ <h3 id="flaginfo" tabindex="-1"><code>FlagInfo</code></h3>
523
+ <pre class="language-ts"><code class="language-ts"><span class="token keyword">interface</span> <span class="token class-name">FlagInfo</span> <span class="token punctuation">{</span>
524
+ alpha2<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">;</span>
525
+ svgUrl<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">;</span> <span class="token comment">// "https://arevdata.com/flags/svg/nl.svg"</span>
526
+ pngUrl<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">;</span> <span class="token comment">// "https://arevdata.com/flags/png/w320/nl.png"</span>
527
+ colors<span class="token operator">:</span> FlagColor<span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">;</span> <span class="token comment">// dominant colours, most prominent first</span>
528
+ similar<span class="token operator">:</span> <span class="token builtin">string</span><span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">;</span> <span class="token comment">// alpha-2 codes of visually similar flags</span>
529
+ <span class="token punctuation">}</span>
530
+ </code></pre>
531
+ <h3 id="geohint" tabindex="-1"><code>GeoHint</code></h3>
532
+ <pre class="language-ts"><code class="language-ts"><span class="token keyword">interface</span> <span class="token class-name">GeoHint</span> <span class="token punctuation">{</span>
533
+ distanceKm<span class="token operator">:</span> <span class="token builtin">number</span><span class="token punctuation">;</span> <span class="token comment">// km between centroids</span>
534
+ direction<span class="token operator">:</span> CardinalDirection<span class="token punctuation">;</span> <span class="token comment">// "N"|"NE"|"E"|"SE"|"S"|"SW"|"W"|"NW"</span>
535
+ temperature<span class="token operator">:</span> <span class="token string">"hotter"</span> <span class="token operator">|</span> <span class="token string">"colder"</span> <span class="token operator">|</span> <span class="token string">"similar"</span><span class="token punctuation">;</span> <span class="token comment">// target vs. guess</span>
536
+ size<span class="token operator">:</span> <span class="token string">"larger"</span> <span class="token operator">|</span> <span class="token string">"smaller"</span> <span class="token operator">|</span> <span class="token string">"similar"</span><span class="token punctuation">;</span> <span class="token comment">// target vs. guess</span>
537
+ hemisphere<span class="token operator">:</span> Hemisphere<span class="token punctuation">;</span>
538
+ landlocked<span class="token operator">:</span> <span class="token builtin">boolean</span><span class="token punctuation">;</span>
539
+ climate<span class="token operator">:</span> ClimateZone<span class="token punctuation">;</span>
540
+ <span class="token punctuation">}</span>
541
+
542
+ <span class="token keyword">interface</span> <span class="token class-name">Hemisphere</span> <span class="token punctuation">{</span>
543
+ ns<span class="token operator">:</span> <span class="token string">"Northern"</span> <span class="token operator">|</span> <span class="token string">"Southern"</span><span class="token punctuation">;</span> <span class="token comment">// latitude ≥ 0 → Northern</span>
544
+ ew<span class="token operator">:</span> <span class="token string">"Eastern"</span> <span class="token operator">|</span> <span class="token string">"Western"</span><span class="token punctuation">;</span> <span class="token comment">// longitude ≥ 0 → Eastern</span>
545
+ <span class="token punctuation">}</span>
546
+ </code></pre>
547
+ <hr>
548
+ <h2 id="detailed-documentation" tabindex="-1">Detailed Documentation</h2>
549
+ <p>Each section has its own reference document:</p>
550
+ <table>
551
+ <thead>
552
+ <tr>
553
+ <th>Section</th>
554
+ <th>Document</th>
555
+ </tr>
556
+ </thead>
557
+ <tbody>
558
+ <tr>
559
+ <td>Countries (ISO codes, flags, phone codes)</td>
560
+ <td><a href="docs/countries.md">docs/countries.md</a></td>
561
+ </tr>
562
+ <tr>
563
+ <td>Phone country codes</td>
564
+ <td><a href="docs/phone-codes.md">docs/phone-codes.md</a></td>
565
+ </tr>
566
+ <tr>
567
+ <td>Cities</td>
568
+ <td><a href="docs/cities.md">docs/cities.md</a></td>
569
+ </tr>
570
+ <tr>
571
+ <td>States, provinces &amp; administrative divisions</td>
572
+ <td><a href="docs/states.md">docs/states.md</a></td>
573
+ </tr>
574
+ <tr>
575
+ <td>Continents &amp; currencies</td>
576
+ <td><a href="docs/continents-currencies.md">docs/continents-currencies.md</a></td>
577
+ </tr>
578
+ <tr>
579
+ <td>Languages, locale variants &amp; speaker estimates</td>
580
+ <td><a href="docs/languages.md">docs/languages.md</a></td>
581
+ </tr>
582
+ <tr>
583
+ <td>Geography data &amp; geo utilities (games)</td>
584
+ <td><a href="docs/geography.md">docs/geography.md</a></td>
585
+ </tr>
586
+ <tr>
587
+ <td>Flags — SVG/PNG URLs, colours, similar flags</td>
588
+ <td><a href="docs/flags.md">docs/flags.md</a></td>
589
+ </tr>
590
+ <tr>
591
+ <td>World map SVG — render, highlight, colorize</td>
592
+ <td><a href="docs/world-map.md">docs/world-map.md</a></td>
593
+ </tr>
594
+ </tbody>
595
+ </table>
596
+ <hr>
597
+ <h2 id="data-coverage" tabindex="-1">Data Coverage</h2>
598
+ <table>
599
+ <thead>
600
+ <tr>
601
+ <th>Region</th>
602
+ <th>Countries</th>
603
+ </tr>
604
+ </thead>
605
+ <tbody>
606
+ <tr>
607
+ <td>Africa</td>
608
+ <td>54</td>
609
+ </tr>
610
+ <tr>
611
+ <td>Asia</td>
612
+ <td>49 (incl. Taiwan, Kosovo, Palestine)</td>
613
+ </tr>
614
+ <tr>
615
+ <td>Europe</td>
616
+ <td>44 (incl. Kosovo, Vatican, San Marino, Monaco, Liechtenstein)</td>
617
+ </tr>
618
+ <tr>
619
+ <td>North America</td>
620
+ <td>23</td>
621
+ </tr>
622
+ <tr>
623
+ <td>South America</td>
624
+ <td>12</td>
625
+ </tr>
626
+ <tr>
627
+ <td>Oceania</td>
628
+ <td>14</td>
629
+ </tr>
630
+ <tr>
631
+ <td><strong>Total</strong></td>
632
+ <td><strong>~195</strong></td>
633
+ </tr>
634
+ </tbody>
635
+ </table>
636
+ <p>States/provinces coverage: United States (50 + DC + territories), Canada (10 provinces + 3 territories), Australia (6 states + 2 territories), Brazil (26 states + DF), Germany (16 Länder), France (13 regions + 5 overseas), Spain (17 autonomous communities), Italy (20 regions), Mexico (31 states + CDMX), India (28 states + 8 UTs), China (23 provinces + 5 AARs + 4 municipalities), Japan (47 prefectures), Switzerland (26 cantons), and more.</p>
637
+ <hr>
638
+ <h2 id="bundle-size" tabindex="-1">Bundle size</h2>
639
+ <table>
640
+ <thead>
641
+ <tr>
642
+ <th>Format</th>
643
+ <th>Size</th>
644
+ <th>Gzip</th>
645
+ </tr>
646
+ </thead>
647
+ <tbody>
648
+ <tr>
649
+ <td>ESM (<code>dist/arev.js</code>)</td>
650
+ <td>~210 kB</td>
651
+ <td>~42 kB</td>
652
+ </tr>
653
+ <tr>
654
+ <td>CJS (<code>dist/arev.cjs</code>)</td>
655
+ <td>~211 kB</td>
656
+ <td>~42 kB</td>
657
+ </tr>
658
+ </tbody>
659
+ </table>
660
+ <p>Flag SVG/PNG images are <strong>not bundled in the npm package</strong>. They are generated from repo-owned SVG sources and hosted on <code>arevdata.com</code>, keeping the package lean while avoiding third-party flag CDNs.</p>
661
+ <hr>
662
+ <h2 id="license" tabindex="-1">License</h2>
663
+ <p>MIT</p>
664
+
665
+ </div>
666
+ </div>
667
+ </section>
668
+ </main>
669
+ </div>
670
+ <footer class="footer">
671
+ <div class="footer__container">
672
+ <div class="footer__controls">
673
+ <div class="footer__control"><span class="footer__label">Theme</span>
674
+ <button class="color-mode-toggle" type="button" data-color-mode-toggle aria-label="Toggle color mode"><span class="color-mode-toggle__value"></span></button>
675
+ </div>
676
+ </div>
677
+ </div>
678
+ </footer>
679
+ </body>
680
+ <script>const isDarkMode = window.matchMedia("prefers-color-scheme: dark").matches;
681
+ let localMode = isDarkMode ? "dark" : "light";
682
+
683
+ const updateColorModeToggle = () => {
684
+ const toggle = document.querySelector("[data-color-mode-toggle]");
685
+ if (!toggle) return;
686
+
687
+ const value = toggle.querySelector(".color-mode-toggle__value");
688
+ if (!value) return;
689
+
690
+ value.textContent = localMode === "dark" ? "Dark" : "Light";
691
+ };
692
+
693
+ const initColorMode = () => {
694
+ localMode = localStorage.getItem("colorMode");
695
+ setCurrentMode(localMode ? localMode : isDarkMode ? "dark" : "light");
696
+ };
697
+
698
+ const setCurrentMode = (mode) => {
699
+ localMode = mode;
700
+ localStorage.setItem("colorMode", localMode);
701
+ document.body.setAttribute("color-mode", mode);
702
+ updateColorModeToggle();
703
+ };
704
+
705
+ const switchMode = () => {
706
+ if (localMode == "dark") setCurrentMode("light");
707
+ else setCurrentMode("dark");
708
+ };
709
+
710
+ const bindColorModeToggle = () => {
711
+ const toggle = document.querySelector("[data-color-mode-toggle]");
712
+ if (!toggle) return;
713
+
714
+ toggle.addEventListener("click", () => {
715
+ switchMode();
716
+ });
717
+ };
718
+
719
+ initColorMode();
720
+ bindColorModeToggle();
721
+ const container = document.querySelector(".container").querySelectorAll("*");
722
+
723
+ container.forEach((el) => {
724
+ const text = el.innerText;
725
+ if (el.innerHTML == el.textContent)
726
+ if (text) {
727
+ const matches = text.match(/#[a-fA-F0-9]{6}|#[a-fA-F0-9]{3}/i);
728
+ if (matches) {
729
+ el.innerHTML = el.innerHTML.replace(
730
+ matches[0],
731
+ `<span class="color-preview" style="--color-preview:${matches[0]}">${matches[0]}</span>`
732
+ );
733
+ }
734
+ }
735
+ });
736
+ const tables = document.querySelectorAll("table");
737
+ let initTableWrap = false;
738
+
739
+ const wrapTables = (tables) => {
740
+ tables &&
741
+ tables.forEach((table) => {
742
+ if (table.getBoundingClientRect().width > window.screen.width) {
743
+ table.classList.add("wrap");
744
+ initTableWrap = true;
745
+ }
746
+ });
747
+ };
748
+
749
+ const labelTables = (tables) => {
750
+ tables &&
751
+ tables.forEach((table) => {
752
+ // Set all headers as attributes to td's
753
+ const headerElements = table.querySelectorAll("thead th");
754
+ const bodyElementRows = table.querySelectorAll("tbody tr");
755
+ const heads = [];
756
+
757
+ if (headerElements && bodyElementRows) {
758
+ // Get TH heads
759
+ headerElements.forEach((th) => {
760
+ heads.push(th.textContent);
761
+ });
762
+ }
763
+
764
+ if (heads.length) {
765
+ bodyElementRows.forEach((tr) => {
766
+ const tds = tr.querySelectorAll("td");
767
+
768
+ tds.forEach((td, i) => {
769
+ td.setAttribute("data-label", heads[i]);
770
+ });
771
+ });
772
+ }
773
+ });
774
+ };
775
+
776
+ wrapTables(tables);
777
+ labelTables(tables);
778
+
779
+ window.addEventListener("resize", () => {
780
+ if (!initTableWrap) wrapTables(tables);
781
+ });
782
+
783
+ </script>
784
+ </html>