arevdata 0.1.17

package/dist/types/data/translations.d.ts

@@ -0,0 +1,73 @@
+import type { Country, City, Continent, Currency } from "../types/index.js";
+/**
+ * Translation record for a single country.
+ */
+export interface CountryTranslation {
+    /** Translated country name */
+    name: string;
+    /** Translated capital city name (optional; omit if same as the English name) */
+    capital?: string;
+}
+/**
+ * All translations for a single language.
+ */
+export interface TranslationMap {
+    /** Country translations keyed by ISO 3166-1 alpha-2 code */
+    countries: Record<string, CountryTranslation>;
+    /** Continent translations keyed by two-letter continent code */
+    continents: Record<string, string>;
+    /** City name translations keyed by English city name */
+    cities: Record<string, string>;
+    /** Currency name translations keyed by ISO 4217 code */
+    currencies: Record<string, string>;
+    /** Language and locale-variant display names keyed by canonical BCP 47 code */
+    languages: Record<string, string>;
+}
+/**
+ * All supported translation language codes (BCP 47 language tags).
+ * English ("en") is the default and is always derived from the source data.
+ */
+export type TranslationLanguage = "en" | "ar" | "de" | "es" | "fr" | "hi" | "it" | "ja" | "ko" | "nl" | "pl" | "pt" | "ru" | "tr" | "zh";
+/**
+ * Translation data for all supported languages.
+ * Each language is defined in its own file under src/data/translations/.
+ * English ("en") is intentionally omitted – the source data already contains English strings.
+ */
+export declare const translations: Record<string, TranslationMap>;
+/**
+ * Return the list of BCP 47 language codes that have translation data.
+ * "en" is always included because the source data is in English.
+ */
+export declare function getSupportedLanguages(): TranslationLanguage[];
+/**
+ * Retrieve the full translation map for a given language code.
+ * Returns `undefined` for unsupported languages (including "en", which uses the
+ * source data directly).
+ */
+export declare function getTranslations(lang: string): TranslationMap | undefined;
+/**
+ * Return a shallow copy of `country` with `name` (and optionally `capital`)
+ * replaced by the translated values for `lang`.
+ * Falls back to the original English values when no translation is found.
+ */
+export declare function translateCountry(country: Country, lang: string): Country;
+/**
+ * Return a shallow copy of `city` with `name` replaced by the translated value
+ * for `lang`. Falls back to the original English name when no translation exists.
+ */
+export declare function translateCity(city: City, lang: string): City;
+/**
+ * Return a shallow copy of `continent` with `name` replaced by the translated
+ * value for `lang`. Falls back to the original English name when no translation exists.
+ */
+export declare function translateContinent(continent: Continent, lang: string): Continent;
+/**
+ * Return a shallow copy of `currency` with `name` replaced by the translated
+ * value for `lang`. Falls back to the original English name when no translation exists.
+ */
+export declare function translateCurrency(currency: Currency, lang: string): Currency;
+/**
+ * Return the translated display name for a language or locale code.
+ * Falls back to the provided English name when no translation exists.
+ */
+export declare function translateLanguageName(code: string, englishName: string, lang: string): string;

package/dist/types/data/worldMap.d.ts

@@ -0,0 +1,122 @@
+/**
+ * World map SVG utilities.
+ *
+ * Provides the vector path data for 251 countries (ISO 3166-1 alpha-2 IDs)
+ * and helper functions to generate, style, and highlight countries in SVG format.
+ *
+ * Path data sourced from the MapSVG world map (http://mapsvg.com).
+ *
+ * @example
+ * ```ts
+ * import { getWorldMapSvg, highlightCountries } from "arevdata";
+ *
+ * // Render a plain world map
+ * document.getElementById("map").innerHTML = getWorldMapSvg({ fill: "#e0e0e0" });
+ *
+ * // Highlight specific countries
+ * document.getElementById("map").innerHTML = highlightCountries(
+ *   [{ code: "US", fill: "#4a90e2" }, { code: "DE", fill: "#e24a4a" }],
+ *   { fill: "#d0d0d0" }
+ * );
+ * ```
+ */
+import type { WorldMapCountry, WorldMapOptions, WorldMapHighlight } from "../types/index.js";
+/** ViewBox for the world map SVG canvas ("0 0 1009.6727 665.96301"). */
+export declare const WORLD_MAP_VIEWBOX = "0 0 1009.6727 665.96301";
+/**
+ * Default styling applied when no options are supplied.
+ */
+export declare const WORLD_MAP_DEFAULTS: Required<WorldMapOptions>;
+/**
+ * SVG path data for every country on the world map.
+ * Paths use ISO 3166-1 alpha-2 codes as identifiers.
+ * All 251 entries include drawable SVG paths.
+ */
+export declare const worldMapCountries: WorldMapCountry[];
+/**
+ * Look up the SVG path data for a single country by its ISO alpha-2 code.
+ * The look-up is case-insensitive.
+ *
+ * @param code ISO 3166-1 alpha-2 code (e.g. "US", "de")
+ * @returns The matching {@link WorldMapCountry} entry, or `undefined` if not found.
+ *
+ * @example
+ * const germany = getCountryMapData("DE");
+ * // { code: "DE", name: "Germany", paths: ["M..."] }
+ */
+export declare function getCountryMapData(code: string): WorldMapCountry | undefined;
+/**
+ * Return all countries whose names contain the given search string
+ * (case-insensitive).
+ *
+ * @param name Full or partial country name
+ * @returns Array of matching {@link WorldMapCountry} entries.
+ *
+ * @example
+ * searchWorldMapCountries("land"); // → Greenland, Iceland, Finland, New Zealand, …
+ */
+export declare function searchWorldMapCountries(name: string): WorldMapCountry[];
+/**
+ * Generate a complete SVG world map string.
+ *
+ * Each country `<path>` element is given:
+ * - `id` set to its ISO alpha-2 code (e.g. `id="DE"`)
+ * - `data-code` – same ISO alpha-2 code
+ * - `data-name` – common country name
+ *
+ * This makes it straightforward to select and style countries via CSS or JavaScript:
+ * ```css
+ * #DE { fill: steelblue; }
+ * ```
+ * ```js
+ * document.getElementById("FR").style.fill = "red";
+ * ```
+ *
+ * @param options Optional styling overrides (merged with {@link WORLD_MAP_DEFAULTS}).
+ * @returns A complete `<svg>…</svg>` string ready for insertion into the DOM.
+ *
+ * @example
+ * const svg = getWorldMapSvg({ fill: "#e8f4f8", stroke: "#aaa", hoverFill: "#4a90e2" });
+ * document.getElementById("map").innerHTML = svg;
+ */
+export declare function getWorldMapSvg(options?: WorldMapOptions): string;
+/**
+ * Generate a world map SVG with specific countries highlighted in custom colours.
+ *
+ * All other countries keep the base fill from `options`.  Each highlighted
+ * country can optionally carry an accessible `<title>` (via `highlight.label`).
+ *
+ * @param highlights Array of {@link WorldMapHighlight} descriptors.
+ * @param options    Optional base styling (merged with {@link WORLD_MAP_DEFAULTS}).
+ * @returns A complete `<svg>…</svg>` string.
+ *
+ * @example
+ * const svg = highlightCountries(
+ *   [
+ *     { code: "US", fill: "#4a90e2", label: "United States" },
+ *     { code: "CA", fill: "#e24a4a" },
+ *   ],
+ *   { fill: "#eeeeee" }
+ * );
+ */
+export declare function highlightCountries(highlights: WorldMapHighlight[], options?: WorldMapOptions): string;
+/**
+ * Generate a world map SVG where countries are coloured by group.
+ *
+ * Useful for choropleth-style maps (e.g. continent groupings, data categories).
+ * Countries not present in any group get the base `options.fill`.
+ *
+ * @param groups  Map from a fill colour to an array of ISO alpha-2 codes.
+ * @param options Optional base styling.
+ * @returns A complete `<svg>…</svg>` string.
+ *
+ * @example
+ * const svg = colorizeWorldMap(
+ *   {
+ *     "#4a90e2": ["US", "CA", "MX"],
+ *     "#e24a4a": ["GB", "DE", "FR"],
+ *   },
+ *   { fill: "#dddddd" }
+ * );
+ */
+export declare function colorizeWorldMap(groups: Record<string, string[]>, options?: WorldMapOptions): string;

package/dist/types/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * arev
+ *
+ * A comprehensive collection of reusable world data:
+ * countries, phone codes, flags, cities, states, provinces, currencies, and more.
+ *
+ * @example
+ * ```ts
+ * import { phoneCountryCodes, countries, cities } from "arevdata";
+ *
+ * // Use phone country codes in a select input
+ * const options = phoneCountryCodes.map(p => ({
+ *   label: `${p.flag} ${p.country} (${p.phoneCode})`,
+ *   value: p.phoneCode,
+ * }));
+ * ```
+ */
+export type { Country, Language, LanguageNameLocale, LanguageOfficialCountry, LanguageOfficialStatus, LanguageType, PhoneCountryCode, City, State, StateType, Continent, ContinentName, Currency, CountryGeography, CountryBounds, ClimateZone, FlagInfo, FlagColor, CardinalDirection, WorldMapCountry, WorldMapOptions, WorldMapHighlight, ReligionBreakdown, EthnicGroup, CountryDemographics, CountryMapOptions, } from "./types/index.js";
+export type { CountryTranslation, TranslationMap, TranslationLanguage, } from "./data/translations.js";
+export { translations, getSupportedLanguages, getTranslations, translateCountry, translateCity, translateContinent, translateCurrency, translateLanguageName, } from "./data/translations.js";
+export { allLanguages, canonicalizeLanguageCode, getLanguageByCode, getLanguageName, getLanguagesBySpeakerCount, getLanguageVariants, getOfficialLanguageCountries, getOfficialLanguagesByCountry, languageCodeAliases, languageNameLocales, languageVariants, languages, officialLanguagesByCountry, searchLanguages, } from "./data/languages/index.js";
+export { countries, getCountryByCode, getCountriesByContinent, getCountryFlag, getRecognizedCountries, } from "./data/countries.js";
+export { phoneCountryCodes, getPhoneCodeByCountry, getCountriesByPhoneCode, } from "./data/phoneCodes.js";
+export { cities, getCitiesByCountry, getCapitalCity, getCitiesByPopulation, searchCities, } from "./data/cities.js";
+export { states, getStatesByCountry, getStateByCode, getStatesByType, } from "./data/states.js";
+export { continents, getContinentByCode } from "./data/continents.js";
+export { currencies, getCurrencyByCode, getCurrencyByCountry, } from "./data/currencies.js";
+export { countryGeography, getCountryGeography, getLandlockedCountries, getCountriesByClimate, getNeighbors, doCountriesBorder, } from "./data/geography.js";
+export { flagData, getFlagData, getFlagsByColor, getSimilarFlags, getFlagSvgUrl, getFlagPngUrl, getCountryMapSvgUrl, } from "./data/flags.js";
+export { haversineDistance, bearing, bearingToCardinal, getDistanceBetweenCountries, getDirectionBetweenCountries, compareTemperature, compareSize, getHemisphere, getGeoHints, } from "./utils/geo.js";
+export type { GeoHint, Hemisphere } from "./utils/geo.js";
+export { WORLD_MAP_VIEWBOX, WORLD_MAP_DEFAULTS, worldMapCountries, getCountryMapData, searchWorldMapCountries, getWorldMapSvg, highlightCountries, colorizeWorldMap, } from "./data/worldMap.js";
+export { COUNTRY_MAP_DEFAULTS, latLonToMapPoint, getCountrySvg, getCountrySubdivisionMapUrl, } from "./data/countryMaps.js";

package/dist/types/types/index.d.ts

@@ -0,0 +1,348 @@
+/**
+ * Represents a country with standard ISO codes and metadata.
+ */
+export interface Country {
+    /** Full official name of the country */
+    name: string;
+    /** Common/short name of the country */
+    nativeName?: string;
+    /** ISO 3166-1 alpha-2 code (e.g., "US") */
+    alpha2: string;
+    /** ISO 3166-1 alpha-3 code (e.g., "USA") */
+    alpha3: string;
+    /** ISO 3166-1 numeric code (e.g., "840") */
+    numeric: string;
+    /** Unicode emoji flag */
+    flag: string;
+    /** International dialing code (e.g., "+1") */
+    phoneCode: string;
+    /** Capital city name */
+    capital: string;
+    /** Continent name */
+    continent: ContinentName;
+    /** ISO 4217 currency code (e.g., "USD") */
+    currency: string;
+    /** Full currency name, optionally translated (e.g., "US Dollar", "US-Dollar") */
+    currencyName?: string;
+    /** Currency symbol (e.g., "$") */
+    currencySymbol?: string;
+    /** Primary language(s) spoken */
+    languages: string[];
+    /** Top-level domain (e.g., ".us") */
+    tld?: string;
+    /**
+     * Whether the country is officially recognized as a sovereign state.
+     * `false` for disputed or unrecognized territories (e.g., Kosovo, Nagorno-Karabakh)
+     * that use user-assigned ISO codes not endorsed by the UN.
+     */
+    recognized: boolean;
+}
+/**
+ * Supported locales used for translated display names in this package.
+ */
+export type LanguageNameLocale = "en" | "ar" | "de" | "es" | "fr" | "hi" | "it" | "ja" | "ko" | "nl" | "pl" | "pt" | "ru" | "tr" | "zh";
+/**
+ * Whether a language entry is a base language code or a more specific locale variant.
+ */
+export type LanguageType = "language" | "variant";
+/**
+ * Official-language statuses used by CLDR territory population data.
+ */
+export type LanguageOfficialStatus = "official" | "de_facto_official" | "official_regional";
+/**
+ * Country-level official-language metadata for a single language.
+ */
+export interface LanguageOfficialCountry {
+    /** ISO 3166-1 alpha-2 country code */
+    countryCode: string;
+    /** Official status in the territory */
+    officialStatus: LanguageOfficialStatus;
+    /** Approximate share of the territory population that speaks the language */
+    populationPercent: number;
+}
+/**
+ * A language or locale variant with translated names and speaker estimates.
+ */
+export interface Language {
+    /** Canonical BCP 47 language or locale code */
+    code: string;
+    /** The canonical base language code, e.g. "en" for "en-GB" */
+    baseCode: string;
+    /** Whether this is a base language or a locale variant */
+    type: LanguageType;
+    /** English display name */
+    name: string;
+    /**
+     * Estimated speaker count derived from CLDR territory population percentages.
+     * For variants this is a locale-scoped estimate where possible.
+     */
+    estimatedSpeakers: number;
+    /** Countries or territories where this language has an official status in CLDR */
+    officialCountries: LanguageOfficialCountry[];
+    /** Script subtag for variants such as "sr-Latn" */
+    script?: string;
+    /** Region subtag for variants such as "en-GB" */
+    region?: string;
+    /** Additional locale variant subtags, e.g. ["valencia"] */
+    variants?: string[];
+}
+/**
+ * Continent names
+ */
+export type ContinentName = "Africa" | "Antarctica" | "Asia" | "Europe" | "North America" | "Oceania" | "South America";
+/**
+ * Phone country code entry, suitable for use in phone number inputs.
+ */
+export interface PhoneCountryCode {
+    /** Country name */
+    country: string;
+    /** ISO 3166-1 alpha-2 code */
+    code: string;
+    /** International dialing code with + prefix (e.g., "+1") */
+    phoneCode: string;
+    /** Unicode emoji flag */
+    flag: string;
+    /** Example number format (without country code) */
+    example?: string;
+}
+/**
+ * Represents a city with geographic and demographic data.
+ */
+export interface City {
+    /** City name */
+    name: string;
+    /** ISO 3166-1 alpha-2 country code */
+    country: string;
+    /** State, province, or region */
+    state?: string;
+    /** Approximate population */
+    population?: number;
+    /** Latitude */
+    lat: number;
+    /** Longitude */
+    lon: number;
+    /** Whether this is the capital of the country */
+    capital?: boolean;
+}
+/**
+ * Represents a state, province, or other administrative division.
+ */
+export interface State {
+    /** Full name of the state/province */
+    name: string;
+    /** State/province abbreviation code */
+    code: string;
+    /** ISO 3166-1 alpha-2 country code */
+    country: string;
+    /** Type of administrative division */
+    type: StateType;
+}
+/**
+ * Types of administrative divisions
+ */
+export type StateType = "state" | "province" | "territory" | "autonomous region" | "district" | "department" | "region" | "county" | "emirate" | "canton";
+/**
+ * Continent with metadata
+ */
+export interface Continent {
+    /** Continent name */
+    name: ContinentName;
+    /** Two-letter continent code */
+    code: string;
+    /** Approximate population */
+    population: number;
+    /** Area in square kilometers */
+    area: number;
+    /** Number of countries */
+    countries: number;
+}
+/**
+ * Currency information
+ */
+export interface Currency {
+    /** ISO 4217 currency code */
+    code: string;
+    /** Currency name */
+    name: string;
+    /** Currency symbol */
+    symbol: string;
+    /** Countries using this currency (alpha-2 codes) */
+    countries: string[];
+}
+/**
+ * Climate zones based on the Köppen climate classification (simplified).
+ */
+export type ClimateZone = "tropical" | "subtropical" | "arid" | "mediterranean" | "temperate" | "continental" | "subarctic" | "arctic";
+/**
+ * Geographic bounding box of a country.
+ */
+export interface CountryBounds {
+    /** Northernmost latitude */
+    north: number;
+    /** Southernmost latitude */
+    south: number;
+    /** Easternmost longitude */
+    east: number;
+    /** Westernmost longitude */
+    west: number;
+}
+/**
+ * Geographic and climate data for a country, useful for geography games.
+ */
+export interface CountryGeography {
+    /** ISO 3166-1 alpha-2 code */
+    alpha2: string;
+    /** Centroid latitude of the country */
+    lat: number;
+    /** Centroid longitude of the country */
+    lon: number;
+    /** Approximate bounding box */
+    bounds: CountryBounds;
+    /** Land area in km² */
+    area: number;
+    /** Whether the country is landlocked (has no coastline) */
+    landlocked: boolean;
+    /** Neighboring country alpha-2 codes */
+    neighbors: string[];
+    /** Primary climate zone */
+    climate: ClimateZone;
+    /** Average annual temperature in Celsius */
+    avgTemperature: number;
+}
+/**
+ * Primary colors that can appear on a country flag.
+ */
+export type FlagColor = "red" | "dark-red" | "white" | "blue" | "green" | "yellow" | "orange" | "black" | "gold" | "light-blue" | "dark-blue" | "dark-green" | "purple" | "brown";
+/**
+ * Flag metadata for a country, including visual similarity data for geography games.
+ */
+export interface FlagInfo {
+    /** ISO 3166-1 alpha-2 code */
+    alpha2: string;
+    /** URL to the hosted SVG flag image */
+    svgUrl: string;
+    /** URL to a hosted 4×3 PNG flag image */
+    pngUrl: string;
+    /** Primary colors present on the flag (up to 4, most prominent first) */
+    colors: FlagColor[];
+    /**
+     * Alpha-2 codes of countries whose flags look visually similar.
+     * Useful for building "guess the flag" games with confusing options.
+     */
+    similar: string[];
+}
+/**
+ * 8-point cardinal / intercardinal compass directions.
+ */
+export type CardinalDirection = "N" | "NE" | "E" | "SE" | "S" | "SW" | "W" | "NW";
+/**
+ * SVG path data for a single country on the world map.
+ * A country may consist of multiple disjoint polygons (e.g. islands).
+ */
+export interface WorldMapCountry {
+    /** ISO 3166-1 alpha-2 code (e.g. "US") */
+    code: string;
+    /** Common country name */
+    name: string;
+    /** One or more SVG path `d` attribute strings */
+    paths: string[];
+}
+/**
+ * Styling options for rendering the world map SVG.
+ */
+export interface WorldMapOptions {
+    /** Fill color for all country shapes. Default: "#d0d0d0" */
+    fill?: string;
+    /** Stroke (border) color between countries. Default: "#ffffff" */
+    stroke?: string;
+    /** Stroke width in SVG units. Default: 0.5 */
+    strokeWidth?: number;
+    /** Fill color applied to a country on hover. Default: "#a0a0a0" */
+    hoverFill?: string;
+    /** SVG element width attribute (e.g. "100%", 800). Default: "100%" */
+    width?: string | number;
+    /** SVG element height attribute (e.g. "auto", 400). Default: "auto" */
+    height?: string | number;
+    /** Optional CSS class added to the `<svg>` element. */
+    className?: string;
+}
+/**
+ * A single religion and its approximate share of a country's population.
+ */
+export interface ReligionBreakdown {
+    /** Religion name (e.g., "Christianity", "Islam", "Hinduism") */
+    name: string;
+    /** Percentage of the population (0–100) */
+    percentage: number;
+}
+/**
+ * A single ethnic group and its approximate share of a country's population.
+ */
+export interface EthnicGroup {
+    /** Ethnic group name (e.g., "Han Chinese", "White", "Mestizo") */
+    name: string;
+    /** Percentage of the population (0–100) */
+    percentage: number;
+}
+/**
+ * Demographic data for a country: population, religions, and ethnic makeup.
+ * Data is sourced from the CIA World Factbook, Pew Research Center, and UN estimates.
+ */
+export interface CountryDemographics {
+    /** ISO 3166-1 alpha-2 code */
+    alpha2: string;
+    /** Approximate total population */
+    population: number;
+    /** Year of the population estimate */
+    populationYear: number;
+    /**
+     * Religious breakdown, sorted by percentage descending.
+     * Percentages may not sum to exactly 100 due to rounding or "other/unspecified" omissions.
+     */
+    religions: ReligionBreakdown[];
+    /**
+     * Ethnic group breakdown, sorted by percentage descending.
+     * Percentages may not sum to exactly 100 due to rounding or "other/unspecified" omissions.
+     */
+    ethnicGroups: EthnicGroup[];
+}
+/**
+ * Describes a highlighted country on the world map.
+ */
+export interface WorldMapHighlight {
+    /** ISO 3166-1 alpha-2 code of the country to highlight */
+    code: string;
+    /** Fill color to use for this country. Overrides the default fill. */
+    fill: string;
+    /** Optional accessible label (written as a `<title>` element). */
+    label?: string;
+}
+/**
+ * Styling and display options for rendering a single-country SVG map.
+ */
+export interface CountryMapOptions {
+    /** Fill color for the country shape. Default: "#d0d0d0" */
+    fill?: string;
+    /** Stroke (border) color for the country outline. Default: "#ffffff" */
+    stroke?: string;
+    /** Stroke width in SVG units. Default: 0.5 */
+    strokeWidth?: number;
+    /** SVG element width attribute (e.g. "100%", 800). Default: "100%" */
+    width?: string | number;
+    /** SVG element height attribute (e.g. "auto", 400). Default: "auto" */
+    height?: string | number;
+    /** Optional CSS class added to the `<svg>` element. */
+    className?: string;
+    /** Whether to show city marker dots. Default: true */
+    showCities?: boolean;
+    /** Fill color for regular city markers. Default: "#555555" */
+    cityColor?: string;
+    /** Fill color for the capital city marker. Default: "#cc2222" */
+    capitalColor?: string;
+    /** Radius of regular city markers in SVG units. Default: 3 */
+    cityRadius?: number;
+    /** Radius of the capital city marker in SVG units. Default: 5 */
+    capitalRadius?: number;
+    /** Extra space (in SVG units) added around the country outline. Default: 5 */
+    padding?: number;
+}

package/dist/types/utils/geo.d.ts

@@ -0,0 +1,101 @@
+import type { CardinalDirection, ClimateZone } from "../types/index.js";
+/**
+ * Calculate the great-circle distance in kilometres between two geographic
+ * coordinates using the Haversine formula.
+ */
+export declare function haversineDistance(lat1: number, lon1: number, lat2: number, lon2: number): number;
+/**
+ * Calculate the initial bearing (in degrees, 0 = north, clockwise) from one
+ * coordinate to another.
+ */
+export declare function bearing(lat1: number, lon1: number, lat2: number, lon2: number): number;
+/**
+ * Convert a bearing in degrees to an 8-point cardinal/intercardinal direction.
+ */
+export declare function bearingToCardinal(deg: number): CardinalDirection;
+/**
+ * Get the great-circle distance in km between two countries (by alpha-2 code),
+ * measured between their geographic centroids.
+ *
+ * Returns `null` if either country code is unknown.
+ */
+export declare function getDistanceBetweenCountries(alpha2A: string, alpha2B: string): number | null;
+/**
+ * Get the compass direction FROM country A TO country B (by alpha-2 code).
+ *
+ * For example, `getDirectionBetweenCountries("FR", "DE")` returns `"NE"`.
+ * Returns `null` if either country code is unknown.
+ */
+export declare function getDirectionBetweenCountries(fromAlpha2: string, toAlpha2: string): CardinalDirection | null;
+/**
+ * Compare the average annual temperature of two countries.
+ *
+ * Returns `"hotter"` if country B is warmer, `"colder"` if cooler, or
+ * `"similar"` if the difference is ≤ 3 °C.
+ *
+ * Useful in geography games: "The target country is hotter than your guess."
+ */
+export declare function compareTemperature(guessAlpha2: string, targetAlpha2: string): "hotter" | "colder" | "similar" | null;
+/**
+ * Compare the size (area) of two countries.
+ *
+ * Returns `"larger"` if the target country is bigger, `"smaller"` if smaller,
+ * or `"similar"` if within 20 % of each other.
+ */
+export declare function compareSize(guessAlpha2: string, targetAlpha2: string): "larger" | "smaller" | "similar" | null;
+/**
+ * Return a human-readable hemisphere description for a country's centroid.
+ *
+ * e.g. `"Northern"` | `"Southern"` | `"Eastern"` | `"Western"`
+ */
+export declare function getHemisphere(alpha2: string): Hemisphere | null;
+/**
+ * Hemisphere of a country: north/south and east/west of the prime meridian/equator.
+ */
+export interface Hemisphere {
+    /** "Northern" if centroid latitude ≥ 0, otherwise "Southern" */
+    ns: "Northern" | "Southern";
+    /** "Eastern" if centroid longitude ≥ 0, otherwise "Western" */
+    ew: "Eastern" | "Western";
+}
+/**
+ * A structured hint object for a geography guessing game.
+ *
+ * Given a player's guess and the secret target, produces all relevant hints.
+ */
+export interface GeoHint {
+    /** Distance from guessed country centroid to target centroid (km) */
+    distanceKm: number;
+    /** Compass direction from guess toward target */
+    direction: CardinalDirection;
+    /** Whether the target is hotter, colder, or similar in temperature */
+    temperature: "hotter" | "colder" | "similar";
+    /** Whether the target is larger, smaller, or similar in area */
+    size: "larger" | "smaller" | "similar";
+    /** Hemisphere of the target country */
+    hemisphere: Hemisphere;
+    /** Whether the target is landlocked */
+    landlocked: boolean;
+    /** Climate zone of the target */
+    climate: ClimateZone;
+}
+/**
+ * Generate all geography game hints comparing a player's guess to the target.
+ *
+ * Returns `null` if either alpha-2 code is not found in the dataset.
+ *
+ * @example
+ * ```ts
+ * const hints = getGeoHints("NL", "DE");
+ * // {
+ * //   distanceKm: 531,
+ * //   direction: "E",
+ * //   temperature: "similar",
+ * //   size: "larger",
+ * //   hemisphere: { ns: "Northern", ew: "Eastern" },
+ * //   landlocked: false,
+ * //   climate: "temperate",
+ * // }
+ * ```
+ */
+export declare function getGeoHints(guessAlpha2: string, targetAlpha2: string): GeoHint | null;