DEV Community

Cover image for We Built and Published an Official JavaScript SDK for Locara
Aim Techno Lab
Aim Techno Lab

Posted on

We Built and Published an Official JavaScript SDK for Locara

#typescript #javascript #webdev #npm

Locara is a developer-first location data API for countries, states, and cities. We built it to make geographic data easy to consume in apps, dashboards, and backend services — and now we’ve made it even easier with an official JavaScript SDK.

This release removes the friction of raw REST calls and gives developers a clean, typed experience for the most common Locara workflows.

Introduction

Locara provides normalized location data for developers who need countries, states, and cities in their applications. It is built for use cases like address forms, regional filtering, travel apps, and analytics dashboards.

An SDK matters because it turns repetitive API plumbing into a simple client interface. Instead of copying fetch code, wiring auth headers, and handling pagination over and over, developers can install a package and start querying location data with a familiar class-based API.

The problem with raw REST

Before this SDK, using Locara required writing your own fetch wrappers around the REST endpoints.

That meant developers had to:

  • set Authorization headers manually,
  • parse JSON responses,
  • normalize error handling,
  • handle rate limits or unexpected HTTP status codes,
  • and write pagination logic for list endpoints.

For teams building production apps, that boilerplate is a real distraction. It also introduces subtle bugs when different parts of the app implement the same API patterns inconsistently.

The SDK removes that friction by providing a single, consistent client that manages authentication, request configuration, and response typing for you.

What's in the SDK

The new locara-js package includes everything needed for modern JavaScript and TypeScript projects.

Install 

npm install locara-js
Enter fullscreen mode Exit fullscreen mode

LocaraClient

The SDK exposes a LocaraClient class that accepts options such as apiKey, baseUrl, and timeout.

This makes it easy to configure the client for different environments, whether you're running in Node.js or the browser.

Three resources

The client includes three primary resources:

  • client.countries
  • client.states
  • client.cities

Each resource is designed around the most common operations developers need to build location-based experiences.

TypeScript types

We included full TypeScript typings for:

  • Country
  • State
  • City
  • PaginatedResponse

That means IDE auto-complete and compile-time validation for the shapes returned by Locara.

LocaraError

The SDK also ships with a LocaraError class.

It exposes:

  • status
  • message
  • code

This makes it easy to distinguish API errors from other runtime issues.

Zero dependencies and modern output

The package is built with zero runtime dependencies and ships as a dual output library:

  • ESM
  • CJS

It supports Node 18+ and browser environments, so you can use it in server-side apps, static sites, or client-side UIs without extra bundler work.

Code examples

Install 

npm install locara-js
Enter fullscreen mode Exit fullscreen mode

Quick start 

import { LocaraClient } from "locara-js";

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

const countries = await client.countries.list({ limit: 10 });
const states = await client.states.list("IN");
const cities = await client.cities.list("US", "CA");
Enter fullscreen mode Exit fullscreen mode

Error handling 

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

try {
  const country = await client.countries.get("XX");
} catch (error) {
  if (error instanceof LocaraError) {
    console.error(error.status); // 404
    console.error(error.message); // "Country not found."
  }
}
Enter fullscreen mode Exit fullscreen mode

What's next for Locara

We’re already working on the next SDK release.

First up is a Python SDK, followed by support for postal/ZIP codes, reverse geocoding, and timezone data.

For full documentation and API details, visit https://www.locara.online/docs.

Closing

If you're building with Locara, give the new JavaScript SDK a try and let us know how it fits into your workflow. We designed it to reduce integration time and make location data easier to use — feedback is welcome.

Originally published at aimtechnolab.com

Top comments (0)