Location Search API

A comprehensive TypeScript/JavaScript library for searching and filtering global city data organized by country. This library provides easy access to a database of cities from around the world.

Installation

npm install location-search-api
# or
yarn add location-search-api
# or
pnpm add location-search-api

Usage

Basic Usage

import LocationAPI from 'location-search-api';

// Search for cities
const results = LocationAPI.searchCities('New');
console.log(results); // ['New York', 'New Delhi', ...]

// Get all cities
const allCities = LocationAPI.getAllCities();

// Get cities by country
const usCities = LocationAPI.getCitiesByCountry('United States');

// Check if a city exists
const exists = LocationAPI.cityExists('Tokyo'); // true

// Get country of a city
const country = LocationAPI.getCountryByCity('Paris'); // 'France'

Named Imports

import { searchCities, getAllCities, getCitiesByCountry } from 'location-search-api';

const cities = searchCities('London', { limit: 10 });

Advanced Search Options

import { searchCities } from 'location-search-api';

// Search with custom limit
const results = searchCities('San', { limit: 5 });

// Case-sensitive search
const results = searchCities('Berlin', { caseSensitive: true });

Using in Next.js API Route

import { NextRequest, NextResponse } from "next/server";
import { searchCities, defaultCities } from 'location-search-api';

export async function GET(request: NextRequest) {
  const url = new URL(request.url);
  const filter = url.searchParams.get("filter");

  if (filter) {
    const filtered = searchCities(filter, { limit: 100 });
    return NextResponse.json({
      status: "ok",
      message: `Filtered Result for ${filter}`,
      data: filtered,
    });
  }

  return NextResponse.json({
    status: "ok",
    message: "Location Search API is healthy",
    data: defaultCities,
  });
}

API Reference

getAllCities()

Returns all cities from all countries as a flat array.

const cities: string[] = LocationAPI.getAllCities();

getAllCountries()

Returns all countries with their cities.

const countries: CityData[] = LocationAPI.getAllCountries();

searchCities(query: string, options?: FilterOptions)

Search cities by name.

Parameters:

• query (string): Search query string
• options (optional): Filter options
  • limit (number): Maximum number of results (default: 100)
  • caseSensitive (boolean): Whether search should be case-sensitive (default: false)

Returns: Array of matching city names

const results = LocationAPI.searchCities('New', { limit: 10 });

getCitiesByCountry(countryName: string)

Get all cities for a specific country.

Parameters:

• countryName (string): Name of the country

Returns: Array of city names or null if country not found

const cities = LocationAPI.getCitiesByCountry('India');

getCountries()

Get all unique country names.

const countries: string[] = LocationAPI.getCountries();

cityExists(cityName: string)

Check if a city exists in the database.

const exists: boolean = LocationAPI.cityExists('Tokyo');

getCountryByCity(cityName: string)

Get the country name for a given city.

Returns: Country name or null if city not found

const country = LocationAPI.getCountryByCity('Paris'); // 'France'

Types

interface CityData {
  country: string;
  cities: string[];
}

interface FilterOptions {
  limit?: number;
  caseSensitive?: boolean;
}

Development

Building

npm run build

This will create:

• dist/index.js (CommonJS)
• dist/index.mjs (ES Modules)
• dist/index.d.ts (TypeScript definitions)

Development Mode

npm run dev

Type Checking

npm run type-check

Publishing

Before publishing, make sure to:

1. Update the repository URL in package.json
2. Build the library: npm run build
3. Publish to npm: npm publish

If publishing a scoped package, make it public:

npm publish --access public

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.