terra-pack

Geographical Data Processing Package

This package provides a set of utilities for handling and processing geographical data such as countries, states, cities, and more. The functions allow you to filter and map countries based on different criteria, calculate distances between coordinates, and retrieve specific geographical data.

Installation

To install the package, run:

npm install terra-pack

Usage

Importing Functions

You can import the functions you need from the package as follows:

import { getCountry, listContinents } from "terra-pack";

Available Functions

• countriesByContinent(continent: string, filter?: exclusion): Get countries by continent.
• countriesBySubContinent(subContinent: string, filter?: exclusion): Get countries by subcontinent.
• listContinents(): List all continents.
• listSubContinents(): List all subcontinents.
• getCountry(countryName: string, filter?: exclusion): Get a country by its name.
• getAllCountries(filter?: exclusion): Get all countries.
• getCountryByISO2(ISO2: string, filter?: exclusion): Get a country by its ISO2 code.
• reverseGeoLocate(latitude: number, longitude: number, extend?: boolean): Find the closest city to a set of coordinates.
• getStatesOfCountry(countryName: string, includeRegions?: boolean): Get states of a specific country.
• getRegionsOfState(stateName: string): Get regions (cities) of a specific state.
• getCountryByCityName(cityName: string, filter?: exclusion): Get a country by a city's name.
• getCountryByStateName(stateName: string, filter?: exclusion): Get a country by a state's name.
• distanceBetweenCoordinates(lat1: number, lon1: number, lat2: number, lon2: number): Calculate the distance between two coordinates.
• getAllStates(filter?: exclusion): Get all states.
• getAllCities(filter?: exclusion): Get all cities.

TypeScript Interfaces

Country

export interface Country {
  name: string;
  iso3: string;
  iso2: string;
  phone_code: string;
  capital: string;
  currency: string;
  currency_name: string;
  tld: string;
  native: string;
  region: string;
  subregion: string;
  nationality: string;
  timezones?: TimeZone[];
  translations?: { [key: string]: string };
  latitude: string;
  longitude: string;
  emoji: string;
  emojiU: string;
  states?: State[];
}

State

export interface State {
  name: string;
  state_code: string;
  latitude: string;
  longitude: string;
  type: "city" | "province" | null;
  cities?: City[];
}

City

export interface City {
  name: string;
  latitude: string;
  longitude: string;
}

GeoLocate

export interface GeoLocate extends City {
  distance: number;
  state?: State;
  country?: Country;
  closestHit?: GeoLocate[];
}

FilterOptions

export type exclusion = Exclude<keyof Country, 'name'>[];

License

This package is licensed under the MIT License.

This README provides a clear overview of the package, instructions on how to install and use it, and details on the available functions and interfaces.