@dr-nio/geo-locator

A lightweight and developer-friendly TypeScript package that converts any address into geographic coordinates using the Open-Meteo Geocoding API. No API key required, no rate limits, and fully free.

🚀 Features

• ✔️ Convert any address into latitude & longitude
• ✔️ Uses a stable, global, free geocoding API
• ✔️ Built with TypeScript
• ✔️ Zero dependencies
• ✔️ Works in Node.js and server environments

📦 Installation

Install the package via npm:

npm install @dr-nio/geo-locator

Or with yarn:

yarn add @dr-nio/geo-locator

🧠 Usage Guide

Basic Example

import { getCoordinates } from "@dr-nio/geo-locator";

async function run() {
  try {
    const coords = await getCoordinates("Ikeja, Lagos, Nigeria");
    console.log("Coordinates:", coords);
  } catch (error) {
    console.error(error);
  }
}

run();

Output Example

{
  lat: 6.605874,
  lng: 3.349149
}

📘 API Reference

getCoordinates(address: string): Promise<Coordinates>

Fetches the latitude and longitude for a given address string.

Parameters:

• address (string) – The location you want to geocode.

Returns:

A Promise that resolves to an object:

interface Coordinates {
  lat: number;
  lng: number;
}

Example Response:

{
  lat: 40.7128,
  lng: -74.0060
}

Throws Errors:

• Empty address passed
• No coordinates found
• Network or API failure

🌍 How It Works

The package uses the Open-Meteo Geocoding API, a free, public, reliable service:

https://geocoding-api.open-meteo.com/v1/search?name=ADDRESS&count=1

This ensures:

• No API key
• Fast response
• High uptime
• Global coverage

⚙️ Development

Build the project

npm run build

Project Structure

src/
  index.ts      → Source code

dist/
  index.js      → Compiled output
  index.d.ts    → Type definitions

📝 License

This project is licensed under the ISC License.

👨‍💻 Author

Dr‑Nio — passionate about developer tools and clean architecture.

⭐ Support the Project

If you find this useful, give the repo a star or share it with other developers!