locara-js

Official JavaScript/TypeScript SDK for the Locara location API. Access countries, states, and cities with full type safety. Works in Node.js 18+ and modern browsers.

Install

npm install locara-js

Quick start

import { LocaraClient } from "locara-js";

const client = new LocaraClient({ apiKey: "loc_live_xxxx" });

// List countries
const countries = await client.countries.list({ page: 1, limit: 10 });
console.log(countries.data[0].name);

// Get a single country
const usa = await client.countries.get("US");
console.log(usa.capital);

// List states in a country
const states = await client.states.list("IN", { page: 1, limit: 50 });

// Get cities in a state
const cities = await client.cities.list("US", "CA", { page: 1, limit: 25 });

Configuration

const client = new LocaraClient({
  apiKey: "loc_live_xxxx",           // required
  baseUrl: "https://www.locara.online/api/v1", // optional, this is the default
  timeout: 30_000,                   // optional, request timeout in ms (default: 30000)
});

API reference

LocaraClient

class LocaraClient {
  constructor(options: { apiKey: string; baseUrl?: string; timeout?: number });

  countries: CountriesResource;
  states: StatesResource;
  cities: CitiesResource;
}

Countries

// GET /countries
client.countries.list(options?: { page?: number; limit?: number }): Promise<PaginatedResponse<Country>>

// GET /countries/:isoCode
client.countries.get(isoCode: string): Promise<Country>

States

// GET /countries/:countryCode/states
client.states.list(countryCode: string, options?: { page?: number; limit?: number }): Promise<PaginatedResponse<State>>

// GET /countries/:countryCode/states/:stateCode
client.states.get(countryCode: string, stateCode: string): Promise<State>

Cities

// GET /countries/:countryCode/states/:stateCode/cities
client.cities.list(countryCode: string, stateCode: string, options?: { page?: number; limit?: number }): Promise<PaginatedResponse<City>>

// GET /countries/:countryCode/states/:stateCode/cities/:cityId
client.cities.get(countryCode: string, stateCode: string, cityId: string): Promise<City>

Types

interface Country {
  id: string;
  name: string;
  isoCode: string;
  iso3: string;
  phoneCode: string;
  capital: string;
  currency: string;
  latitude: string;
  longitude: string;
}

interface State {
  id: string;
  name: string;
  isoCode: string;
  countryCode: string;
  latitude: string;
  longitude: string;
}

interface City {
  id: string;
  name: string;
  stateCode: string;
  countryCode: string;
  latitude: string;
  longitude: string;
}

interface PaginatedResponse<T> {
  success: boolean;
  data: T[];
  pagination: {
    total: number;
    page: number;
    limit: number;
    totalPages: number;
  };
}

Error handling

Non-2xx responses throw a LocaraError with status, message, and code fields:

import { LocaraClient, LocaraError } from "locara-js";

const client = new LocaraClient({ apiKey: "loc_live_xxxx" });

try {
  const country = await client.countries.get("XX");
} catch (error) {
  if (error instanceof LocaraError) {
    console.error(error.status);  // e.g. 404
    console.error(error.message); // e.g. "Country not found."
    console.error(error.code);    // e.g. "NOT_FOUND"
  } else {
    throw error;
  }
}

Documentation

For full API documentation, authentication details, and pagination guides, visit:

https://www.locara.online/docs

License

MIT