Full-Text Search API

Search across all place names with fuzzy matching. Filter results by admin level and country code.

Search Places

Search places by name query string.

GET /api/v1/fts/search

Query Parameters

Parameter	Type	Required	Description
query	string	Yes	Search term (e.g. "London", "Istanbul")
admin_level	number	No	Filter by admin level (2-15)
country_code	string	No	Filter by ISO country code lowercase (e.g. "tr", "us", "gb")
limit	number	No	Max results (default: 10)
offset	number	No	Pagination offset (default: 0)

Example

curl -H "X-API-Key: YOUR_KEY" \
     "https://api-piriapi.kaanksc.com/api/v1/fts/search?query=London&limit=5"

Example with Filters

curl -H "X-API-Key: YOUR_KEY" \
     "https://api-piriapi.kaanksc.com/api/v1/fts/search?query=London&country_code=gb&admin_level=5"

Response

{
  "list": [
    {
      "id": "GHFAEKI",
      "admin_level": 5,
      "localname": "Greater London",
      "coordinates": [-0.1277653, 51.5074456],
      "country_code": "gb",
      "names": {
        "en": "Greater London",
        "de": "Groß-London",
        "fr": "Grand Londres",
        "tr": "Büyük Londra",
        ... // 100+ languages
      },
      "address": [
        { "id": "GHFAEKI", "localname": "Greater London", "admin_level": 5 },
        { "id": "LHHKAI", "localname": "England", "admin_level": 4 },
        { "id": "FEHMAJ", "localname": "United Kingdom", "admin_level": 2 }
      ]
    }
  ],
  "limit": 5,
  "offset": 0,
  "count": 8
}

Response Types

Place

interface Place {
  id: string;              // PiriID (e.g. "GHFAEKI")
  admin_level: number;     // 2=country, 3=region, 4=state, 5=county, 8=city, 15=sub-locality
  localname: string;       // Name in local language
  coordinates: number[];   // [longitude, latitude]
  country_code: string;    // ISO 3166-1 alpha-2 lowercase (e.g. "gb", "tr")
  names: Record<string, string>;  // Multi-language names (100+ languages)
  address: Address[];      // Parent hierarchy chain
}

interface Address {
  id: string;              // PiriID
  localname: string;
  admin_level: number;
}

PlacesResponse

interface PlacesResponse {
  list: Place[];
  limit: number;
  offset: number;
  count: number;   // Total matching results
}