PiriAPI Docs

Places API

Browse hierarchical geographic data. Access countries, regions, and sub-regions with multi-language names and coordinates.

List Countries

Returns all countries (top-level places).

GET /api/v1/places

Query Parameters

Parameter	Type	Default	Description
limit	number	-1	Max results (-1 for all)
offset	number	0	Pagination offset

Example

curl -H "X-API-Key: YOUR_KEY" \
     "https://api-piriapi.kaanksc.com/api/v1/places?limit=10"

Response

{
  "list": [
    {
      "id": "EFAELFDM",
      "admin_level": 2,
      "localname": "Turkey",
      "coordinates": [35.0, 39.0],
      "country_code": "tr",
      "names": {
        "en": "Turkey",
        "tr": "Türkiye",
        "de": "Türkei",
        "fr": "Turquie",
        "es": "Turquía",
        "ja": "トルコ",
        "zh": "土耳其",
        ... // 100+ languages
      },
      "address": []
    }
  ],
  "limit": 10,
  "offset": 0,
  "count": 221
}

Get Place by ID

Returns detailed information about a specific place.

GET /api/v1/places/{id}

Path Parameters

Parameter	Type	Description
id	string	Place ID (PiriID)

Example

curl -H "X-API-Key: YOUR_KEY" \
     "https://api-piriapi.kaanksc.com/api/v1/places/EFAELFDM"

Response

{
  "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",
    "es": "Gran Londres",
    "ja": "グレーターロンドン",
    "zh": "大伦敦",
    ... // 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 }
  ]
}

List Sub-Regions

Returns child places of a given parent. Use this to navigate the hierarchy (country → region → sub-region).

GET /api/v1/places/{id}/sub-regions

Path Parameters

Parameter	Type	Description
id	string	Parent place ID

Query Parameters

Parameter	Type	Default	Description
limit	number	-1	Max results
offset	number	0	Pagination offset
admin-levels	number[]	[]	Filter by admin levels

Example

curl -H "X-API-Key: YOUR_KEY" \
     "https://api-piriapi.kaanksc.com/api/v1/places/FEHMAJ/sub-regions?limit=5"

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
  admin_levels?: number[];  // Available admin levels (sub-regions only)
}