Locations

The Location object represents a geographical area used in listings and requests. Locations are organized in a 3-level hierarchy: Περιοχή (Region, level 1) → Υποπεριοχή (Sub-region, level 2) → Γειτονιά (Neighbourhood, level 3).

System locations are pre-loaded and read-only. Custom locations created by users are marked with user_created: true.

Object

Example

{
  "id": 42,
  "name_el": "Κολωνάκι",
  "name_en": "Kolonaki",
  "level": 3,
  "parent_id": 12,
  "full_tree_name_el": "Αττική > Κεντρικός Τομέας > Κολωνάκι",
  "full_tree_name_en": "Attica > Central Sector > Kolonaki",
  "user_created": false
}

• id (int): The unique system ID of the location.
• name_el (string): The location name in Greek.
• name_en (string): The location name in English.
• level (int): The hierarchy level. 1 = Περιοχή, 2 = Υποπεριοχή, 3 = Γειτονιά.
• parent_id (int, nullable): The ID of the parent location, or null for level 1 entries.
• full_tree_name_el (string, nullable): The full path name in Greek (e.g. "Αττική > Κεντρικός Τομέας > Κολωνάκι").
• full_tree_name_en (string, nullable): The full path name in English.
• user_created (boolean): true if this location was created by a user, false if it is a system location.

Get locations

/api/locations (GET)

Fetch a paginated list of locations. Supports filtering by ID, name, level, and parent.

Request

• Method: GET
• Headers: Include authentication headers as described in the Authentication section.
• Body: JSON object with the following optional parameters:
  • page (int): The page number to fetch. Defaults to 1. Each page returns up to 100 results.
  • search (string): Search across name_el, name_en, full_tree_name_el, and full_tree_name_en using a partial match.
  • id (int): Return the location with this exact ID.
  • level (int): Filter by hierarchy level. Accepted values: 1, 2, 3.
  • parent_id (int): Filter by parent location ID. Useful for fetching all sub-regions of a region, or all neighbourhoods of a sub-region.

Example Body

Fetch all level-2 locations under region ID 5:

{
  "level": 2,
  "parent_id": 5
}

Search for locations matching "Κολωνάκι":

{
  "search": "Κολωνάκι"
}

Look up a location by exact ID:

{
  "id": 42
}

Response

• 200 OK: Returns a paginated JSON object.

Example Response

{
  "status": 200,
  "page": 1,
  "total_pages": 3,
  "results_per_page": 100,
  "total_results": 284,
  "data": [
    {
      "id": 1,
      "name_el": "Αττική",
      "name_en": "Attica",
      "level": 1,
      "parent_id": null,
      "full_tree_name_el": "Αττική",
      "full_tree_name_en": "Attica",
      "user_created": false
    },
    {
      "id": 12,
      "name_el": "Κεντρικός Τομέας",
      "name_en": "Central Sector",
      "level": 2,
      "parent_id": 1,
      "full_tree_name_el": "Αττική > Κεντρικός Τομέας",
      "full_tree_name_en": "Attica > Central Sector",
      "user_created": false
    }
  ]
}

Get single location

/api/locations/{id} (GET)

Fetch a single location by its ID.

Request

• Method: GET
• Headers: Include authentication headers.
• Path Parameters: The location ID to fetch.

Example Response

{
  "status": 200,
  "data": {
    "id": 42,
    "name_el": "Κολωνάκι",
    "name_en": "Kolonaki",
    "level": 3,
    "parent_id": 12,
    "full_tree_name_el": "Αττική > Κεντρικός Τομέας > Κολωνάκι",
    "full_tree_name_en": "Attica > Central Sector > Kolonaki",
    "user_created": false
  }
}

Error Responses

• 404 Not Found: No location exists with the given ID.

{
  "status": 404,
  "error_message": "Location not found."
}