API Reference

Install

npm install locara-js # JavaScript / TypeScriptpip install locara # Python

Welcome to the Locara API documentation. Our platform provides the most comprehensive and up-to-date geographical data ecosystem, matching industry standards. Access countries, states, and cities seamlessly through our deeply nested RESTful API.

The current API version is v1. The base URL for all requests is https://www.locara.online/api/v1 .

Quickstart

Get started with our SDKs or raw HTTP requests in minutes. First, get your API key from the dashboard, then make your first request.

curl --location 'https://www.locara.online/api/v1/countries' \
--header 'Authorization: Bearer YOUR_API_KEY'

Authentication

All API requests require authentication via an API Key. Pass your key in the Authorization header using the Bearer schema.

HTTP Header

Authorization: Bearer YOUR_API_KEY

Get All Countries

GET/countries

Retrieve a paginated list of all countries in the database.

Query Parameters

limitnumber

Limit results per page (Default: 50).

offsetnumber

Pagination offset.

searchstring

Search by country name or ISO.

curl --location 'https://www.locara.online/api/v1/countries' \
--header 'Authorization: Bearer <API_KEY>'

Response

{
  "success": true,
  "data": [
    {
      "id": "1",
      "name": "United States",
      "iso2": "US",
      "iso3": "USA",
      "phonecode": "1"
    }
  ],
  "pagination": { "total": 250, "limit": 50, "offset": 0, "hasMore": true }
}

Get Single Country

GET/countries/[ciso]

Retrieve specific details of a single country by passing its ISO2 code.

Path Parameters

cisostringRequired

The ISO2 code of the country (e.g. US, IN).

curl --location 'https://www.locara.online/api/v1/countries/US' \
--header 'Authorization: Bearer <API_KEY>'

Response

{
  "success": true,
  "data": {
    "id": "1",
    "name": "United States",
    "iso2": "US",
    "iso3": "USA",
    "phonecode": "1"
  }
}

Get States of Country

GET/countries/[ciso]/states

Retrieve a paginated list of all states or provinces belonging to a specific country.

Path Parameters

cisostringRequired

The ISO2 code of the country (e.g. IN).

curl --location 'https://www.locara.online/api/v1/countries/IN/states' \
--header 'Authorization: Bearer <API_KEY>'

Response

{
  "success": true,
  "data": [
    {
      "id": "...",
      "name": "Maharashtra",
      "code": "MH",
      "countryId": "..."
    }
  ],
  "pagination": { "total": 36, "limit": 50, "offset": 0, "hasMore": false }
}

Get Single State

GET/countries/[ciso]/states/[siso]

Retrieve specific details of a single state within a country.

Path Parameters

cisostringRequired

The ISO2 code of the country.

sisostringRequired

The ISO code of the state.

curl --location 'https://www.locara.online/api/v1/countries/IN/states/MH' \
--header 'Authorization: Bearer <API_KEY>'

Response

{
  "success": true,
  "data": {
    "id": "...",
    "name": "Maharashtra",
    "code": "MH",
    "countryId": "..."
  }
}

Get Cities of Country

GET/countries/[ciso]/cities

Retrieve a paginated list of all cities belonging to a specific country across all its states.

Path Parameters

cisostringRequired

The ISO2 code of the country.

curl --location 'https://www.locara.online/api/v1/countries/US/cities' \
--header 'Authorization: Bearer <API_KEY>'

Response

{
  "success": true,
  "data": [
    {
      "id": "...",
      "name": "New York City",
      "stateId": "...",
      "latitude": "40.7128",
      "longitude": "-74.0060"
    }
  ],
  "pagination": { "total": 19500, "limit": 50, "offset": 0, "hasMore": true }
}

Get Cities of State

GET/countries/[ciso]/states/[siso]/cities

Retrieve a paginated list of all cities belonging to a specific state.

Path Parameters

cisostringRequired

The ISO2 code of the country.

sisostringRequired

The ISO code of the state.

curl --location 'https://www.locara.online/api/v1/countries/US/states/CA/cities' \
--header 'Authorization: Bearer <API_KEY>'

Response

{
  "success": true,
  "data": [
    {
      "id": "...",
      "name": "Los Angeles",
      "stateId": "...",
      "latitude": "34.0522",
      "longitude": "-118.2437"
    }
  ],
  "pagination": { "total": 1150, "limit": 50, "offset": 0, "hasMore": true }
}

Search

GET/search

Search across all countries, states, and cities in a single request. Returns a ranked list of matching results with their type and parent context.

Query Parameters

qstringRequired

Search term, minimum 2 characters.

typestring

Filter by "country", "state", or "city".

limitnumber

Results per page, max 50, default 10.

offsetnumber

Pagination offset, default 0.

// Example 1 — Basic search
curl --location 'https://www.locara.online/api/v1/search?q=india' \
--header 'Authorization: Bearer <API_KEY>'

// Example 2 — Filtered search
curl --location 'https://www.locara.online/api/v1/search?q=gujarat&type=state' \
--header 'Authorization: Bearer <API_KEY>'

Response

{
  "success": true,
  "data": [
    {
      "id": "...",
      "name": "India",
      "type": "country"
    },
    {
      "id": "...",
      "name": "Indiana",
      "type": "state",
      "country": { "iso2": "US", "name": "United States" }
    },
    {
      "id": "...",
      "name": "Indianapolis",
      "type": "city",
      "country": { "iso2": "US", "name": "United States" },
      "state": { "code": "IN", "name": "Indiana" }
    }
  ],
  "pagination": { "total": 42, "limit": 10, "offset": 0, "hasMore": true }
}