{
  "openapi": "3.0.1",
  "info": {
    "title": "Oikotie Property Scraper",
    "description": "Scrape asunnot.oikotie.fi: homes for sale and rent, holiday homes, plots, garages and farms. Prices, m2, rooms, hoitovastike, energy class, GPS and agent contacts.",
    "version": "1.0",
    "x-build-id": "yLodBEpzVFoDLMnkv"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/sian.agency~oikotie-property-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-sian.agency-oikotie-property-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/sian.agency~oikotie-property-scraper/runs": {
      "post": {
        "operationId": "runs-sync-sian.agency-oikotie-property-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/sian.agency~oikotie-property-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-sian.agency-oikotie-property-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "operation": {
            "title": "🎯 What do you want to scrape?",
            "enum": [
              "search",
              "listingDetail",
              "agencyDirectory"
            ],
            "type": "string",
            "description": "Pick one per run. Property Search sweeps Oikotie's own card endpoint by area and filter and returns 100 listing rows per call, across all ten Oikotie sections. Listing Detail takes Oikotie listing URLs or numeric ids and returns the full record — housing-company fees, energy class, renovation history, every photo and the selling agent's direct phone. Estate Agency Directory returns Finland's registered Oikotie brokerage offices with phone, email, website and business ID.",
            "default": "search"
          },
          "section": {
            "title": "🏘️ Oikotie section",
            "enum": [
              "homesForSale",
              "homesForRent",
              "holidayHomesForSale",
              "holidayHomesForRent",
              "plots",
              "forestAndFarms",
              "garagesForSale",
              "garagesForRent",
              "commercialForSale",
              "commercialForRent"
            ],
            "type": "string",
            "description": "Which part of Oikotie to search. Homes for sale is the big one (142,200 live listings) and homes to rent holds 26,500. Each section returns a slightly different row shape: rentals carry a monthly rent instead of an asking price, plots and forest estates carry lot area but no living area, and commercial premises live on Oikotie's toimitilat front so their URLs point there. Ignored by the Listing Detail and Estate Agency Directory operations.",
            "default": "homesForSale"
          },
          "locations": {
            "title": "📍 Areas",
            "type": "array",
            "description": "Finnish place names: Helsinki, Espoo, Tampere, Turku, Oulu, Jyväskylä, Kallio, Uusimaa. Each name is matched against Oikotie's own live location tree, so a city, a city district, a region or a postcode area all work and spelling follows Oikotie. One search runs per area, in the order you list them, and every area shares the single Max results budget below. Leave empty to sweep the whole of Finland. The Estate Agency Directory uses this list too — it keeps only offices in the cities you name.",
            "default": [
              "Helsinki"
            ],
            "items": {
              "type": "string"
            }
          },
          "sortBy": {
            "title": "↕️ Sort by",
            "enum": [
              "newest",
              "oldest",
              "priceAsc",
              "priceDesc",
              "largest"
            ],
            "type": "string",
            "description": "Newest first is what you want for monitoring a market on a schedule — a daily run then only has to read the top of the list. Price, low to high is the one that surfaces the cheap end of a district.",
            "default": "newest"
          },
          "maxResults": {
            "title": "🔢 Max results",
            "minimum": 1,
            "maximum": 20000,
            "type": "integer",
            "description": "Hard ceiling on the rows this run returns and bills for, shared across every area you listed. 50 is a cheap look at a market; a full sweep of Helsinki's for-sale stock is about 8,100. Paging is 100 rows per request, so the run costs the same per row whatever you set.",
            "default": 50
          },
          "minPrice": {
            "title": "💶 Min price (€)",
            "minimum": 0,
            "type": "integer",
            "description": "Lowest asking price to include, in euros. For rentals this is the monthly rent. 0 means no lower bound.",
            "default": 0
          },
          "maxPrice": {
            "title": "💶 Max price (€)",
            "minimum": 0,
            "type": "integer",
            "description": "Highest asking price to include, in euros. For rentals this is the monthly rent. 0 means no upper bound.",
            "default": 0
          },
          "minSizeSqm": {
            "title": "📏 Min size (m²)",
            "minimum": 0,
            "type": "integer",
            "description": "Smallest living area to include, in square metres. 0 means no lower bound. Plots and forest estates are filtered on lot area instead.",
            "default": 0
          },
          "maxSizeSqm": {
            "title": "📏 Max size (m²)",
            "minimum": 0,
            "type": "integer",
            "description": "Largest living area to include, in square metres. 0 means no upper bound.",
            "default": 0
          },
          "rooms": {
            "title": "🚪 Rooms",
            "enum": [
              "any",
              "1",
              "2",
              "3",
              "4",
              "5",
              "6",
              "7plus"
            ],
            "type": "string",
            "description": "Oikotie counts rooms the Finnish way — a yksiö is 1, a kaksio is 2, and the kitchen is not counted. 7 rooms or more asks Oikotie for every count from 7 up.",
            "default": "any"
          },
          "propertyType": {
            "title": "🏗️ Building type",
            "enum": [
              "any",
              "apartmentBuilding",
              "rowHouse",
              "detachedHouse",
              "semiDetached",
              "separateHouse",
              "loftHouse",
              "woodenApartment",
              "other"
            ],
            "type": "string",
            "description": "Finnish building categories as Oikotie files them. Kerrostalo dominates the cities — 828 of the first 1,000 Helsinki for-sale listings — while omakotitalo and rivitalo carry the suburbs. Ignored for plots, forest estates and garages, which have no building type.",
            "default": "any"
          },
          "minYearBuilt": {
            "title": "📅 Built from year",
            "minimum": 0,
            "maximum": 2100,
            "type": "integer",
            "description": "Earliest construction year to include. 0 means no lower bound. Useful for skipping the 1970s pipe-renovation cohort.",
            "default": 0
          },
          "maxYearBuilt": {
            "title": "📅 Built up to year",
            "minimum": 0,
            "maximum": 2100,
            "type": "integer",
            "description": "Latest construction year to include. 0 means no upper bound.",
            "default": 0
          },
          "newDevelopmentOnly": {
            "title": "🏗️ New developments only",
            "type": "boolean",
            "description": "Keep only uudiskohteet — units sold new by the developer rather than resold by an owner. About a quarter of Helsinki's for-sale stock.",
            "default": false
          },
          "fullDetails": {
            "title": "📄 Add full details to every row",
            "type": "boolean",
            "description": "Off, a search row carries what Oikotie's result cards carry: price, size, rooms, address, coordinates, agency and agent name. On, each row also gets its listing page fetched for the full description, housing-company fees, energy class, renovation history, every photo and the agent's direct phone — one extra request per row, billed as one Detail Enrichment. Leave it off for a wide market sweep and on for a shortlist.",
            "default": false
          },
          "listingUrls": {
            "title": "🔗 Listing URLs or IDs",
            "type": "array",
            "description": "Used by the Listing Detail operation only. Paste Oikotie listing URLs — https://asunnot.oikotie.fi/myytavat-asunnot/helsinki/24678422, or the toimitilat equivalent for commercial premises. Apify validates this field as a URL list, so a bare listing number is rejected before the run starts; copy the address bar instead. Upload a file or link a Google Sheet to run a saved shortlist.",
            "default": [],
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "agencyQuery": {
            "title": "🏢 Agency name contains",
            "type": "string",
            "description": "Used by the Estate Agency Directory operation only. Keeps offices whose name, official name or parent group contains this text — Habita, Kiinteistömaailma, OP Koti, RE/MAX. Leave empty for every office in the areas you listed, or for all 1,791 offices in Finland if you listed none.",
            "default": ""
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}