Libraries

Five official packages ship with Geomelon: zero-dependency TypeScript and Python clients, a headless React hook/component, an MCP server that exposes the API as AI tools, and an n8n community node for visual workflow automation.

Looking for offline/static data instead of live API calls? See the per-country npm data packages at geomelon.dev/data-packages.

---

TypeScript Client

Package: geomelon
Source: github.com/930m310n/typescript

A typed, zero-dependency client for the Geomelon RapidAPI gateway. Works in Node.js 18+ and any environment with native fetch.

Install

npm install geomelon

Usage

import { GeomelonClient } from "geomelon";

const client = new GeomelonClient({ apiKey: "YOUR_RAPIDAPI_KEY" });

// Search cities with localized names
const cities = await client.cities.search({
  name: "Paris",
  preferredLanguages: "fr,en",
  limit: 10,
});

// Filter countries by name prefix
const countries = await client.countries.list({
  name: "Fra",
  preferredLanguages: "fr",
});

// Nearest cities to a point
const nearby = await client.cities.byCoordinatesClosest({
  lat: 48.8566,
  lon: 2.3522,
  preferredLanguages: "fr,en",
});

Sub-clients

Client	Methods
client.cities	search, get, translations, settlementTypes, distance, byCoordinatesClosest, byCoordinatesLargest
client.countries	list, get, translations, regions
client.regions	list, get, translations
client.languages	list, get

Dual module build

The package ships both CommonJS and ESM builds. Use whichever your bundler or runtime prefers — the exports field in package.json handles resolution automatically.

---

Python Client

Package: geomelon
Source: github.com/930m310n/python

A typed, zero-dependency Python client — standard library only, Python 3.8 through 3.14, dataclass models with full type hints (py.typed, works with mypy/pyright).

Install

pip install geomelon

Try it without an API key

The free oneshot autocomplete works with zero signup:

from geomelon import GeomelonClient

client = GeomelonClient()  # no key
for city in client.oneshot.search("es", "es", "barc"):
    print(city.name, city.population, city.emoji)
# Barcelona 1620343 🇪🇸

Prefixes are normalized server-side — "Barç", "barc", and "BARC" all find Barcelona.

Full API usage

from geomelon import GeomelonClient, GeomelonError

client = GeomelonClient(api_key="YOUR_RAPIDAPI_KEY")

# Search cities with localized names
cities = client.cities.search(name="barc", country_code="ES", preferred_languages="es,en")

# Nearest cities to a point
nearby = client.cities.by_coordinates_closest(41.3828, 2.1769, preferred_languages="es")

# Countries, regions, languages
spain = client.countries.get("a1e06cc1-817c-429f-84f4-6ab51dac9bfa")

# Typed errors with a rate-limit shortcut
try:
    client.cities.search(name="barc")
except GeomelonError as err:
    if err.is_rate_limited:
        ...

Sub-clients

Client	Methods
client.cities	search, get, translations, settlement_types, distance, by_coordinates_closest, by_coordinates_largest
client.countries	list, get, translations, regions
client.regions	list, get, translations
client.languages	list, get
client.oneshot	search

Parameters are snake_case keyword arguments mapping 1:1 to the API’s camelCase; unknown response fields are ignored, so API additions never break an installed client.

---

React

Package: geomelon-react
Source: github.com/930m310n/geomelon-react

A headless React hook and component for city autocomplete, built on the free, keyless oneshot prefix search — no API key, no backend proxy required.

Install

npm install geomelon-react

react (>=16.8) is a peer dependency; it depends on geomelon for the underlying fetch/retry/error logic.

The hook

import { useState } from "react";
import { useCityAutocomplete } from "geomelon-react";

function CityField() {
  const [query, setQuery] = useState("");
  const { results, loading, error } = useCityAutocomplete({
    countryIso: "es",
    lang: "es",
    query,
  });

  return (
    <div>
      <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="Start typing a city..." />
      <ul>
        {results.map((city) => (
          <li key={city.id}>{city.emoji} {city.name}</li>
        ))}
      </ul>
    </div>
  );
}

Debounces (150ms default), cancels in-flight requests on change, and returns a typed GeomelonError rather than swallowing failures.

The component

<CityAutocomplete> is a ready-made input + dropdown with ARIA combobox semantics and keyboard navigation (ArrowUp/ArrowDown/Enter/Escape) — headless, no shipped CSS:

import { CityAutocomplete } from "geomelon-react";

<CityAutocomplete
  countryIso="es"
  lang="es"
  placeholder="Start typing a city..."
  onSelect={(city) => console.log(city.name)}
/>

A runnable example lives at examples/vite-react, also openable directly in StackBlitz.

---

MCP Server

Package: geomelon-mcp

An MCP (Model Context Protocol) server that exposes Geomelon as a set of tools for AI assistants and agents. Supports both stdio and remote HTTP transports.

Try it without an API key

No GEOMELON_API_KEY? The server still starts up, exposing just search_cities_autocomplete — backed by the free oneshot host, no signup required. A public hosted instance of this same keyless mode is also live at https://mcp.geomelon.dev/mcp for any remote-MCP-capable client, no local install needed.

Install

npm install -g geomelon-mcp

Or run directly:

GEOMELON_API_KEY=YOUR_RAPIDAPI_KEY npx geomelon-mcp

Omit GEOMELON_API_KEY to run in keyless demo mode.

Available tools

Tool	Description
search_cities	Search cities by name, country, population range
get_city	Full details for a city UUID
get_city_translations	All name translations for a city
get_city_settlement_types	Settlement-type classifications for a city
cities_by_coordinates_closest	Cities nearest to coordinates
cities_by_coordinates_largest	Most populous cities near coordinates
cities_distance	Distance in km between two cities
list_countries	List countries, filter by name or telephone code
get_country	Full country details including regions
get_country_translations	Name translations for a country
get_country_regions	All regions belonging to a country
list_regions	Regions, filtered by country
get_region	Full region details
get_region_translations	Name translations for a region
list_languages	Languages in the database
get_language	Single language by UUID

Oneshot prefix search (free, no API key)

Tool	Description
search_cities_autocomplete	Country-scoped, language-specific city name prefix search backed by pre-built static files. The only tool available in keyless demo mode. Works in keyed mode too — it’s the fastest search path.

Compound tools

These tools chain multiple API calls to save round-trips when an AI agent needs combined data.

Tool	Description
find_cities_near_city	Given a city UUID, find nearby cities by distance or population
city_context	Fetch a city with its full country and region details in one call
country_overview	Fetch a country (by UUID or name), its regions, and top cities
compare_cities	Fetch two cities and the distance between them in one call
search_cities_in_country	Search cities using a country name instead of an ISO code

Claude Desktop config

{
  "mcpServers": {
    "geomelon": {
      "command": "npx",
      "args": ["-y", "geomelon-mcp"],
      "env": {
        "GEOMELON_API_KEY": "YOUR_RAPIDAPI_KEY"
      }
    }
  }
}

Omit the env block entirely to run in keyless demo mode.

---

n8n Community Node

Package: n8n-nodes-geomelon
Source: github.com/930m310n/n8n-nodes-geomelon

An n8n community node for using Geomelon inside visual workflows. Search cities, look up countries and regions, compute distances, and resolve coordinates — all as drag-and-drop steps.

Install

In your n8n instance: Settings → Community Nodes → Install → enter n8n-nodes-geomelon.

Requires n8n v1.0+ and Node.js 18+.

Available operations

Resource	Operations
City	Search, Get, Get Translations, Get Settlement Types, Distance, By Coordinates (Closest), By Coordinates (Largest)
Country	List, Get, Get Translations, Get Regions
Region	List, Get, Get Translations
Language	List, Get

Example workflow

Connect a Geomelon node set to Country → List (name = Germany) into a second node set to Country → Get Regions, then into a third set to City → Search (sort = population_desc). Each node fans out one item per result, so downstream nodes iterate naturally.

---

OpenAPI Specification

The full API surface — every endpoint, parameter, and response schema — is published as an OpenAPI 3.0 document:

geomelon.dev/openapi.json

Use it to generate clients for languages we don’t ship yet (openapi-generator supports 60+ targets), import the API into Postman or Insomnia, or wire up your own tooling.