add missing endpoints

Author: spekulatius

CLAUDE.md

@@ -0,0 +1,61 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+PHP client library for 4 Apify actors that scrape Yandex data: places/businesses from Yandex Maps, reviews from Yandex Maps, products from Yandex Market, and real estate listings from Yandex Realty. Returns typed DTOs for each data type.
+
+## Build Commands
+
+```bash
+composer install          # Install dependencies
+composer test             # Run Pest tests
+composer test -- --filter TestName  # Run single test
+composer cs               # Check code style (Laravel Pint)
+composer cs:fix           # Fix code style
+composer analyse          # Run PHPStan static analysis (level 8)
+```
+
+## Architecture
+
+```
+src/
+  Client.php              # Main API client with 4 scraping methods
+  Config.php              # Configuration (API token, actor IDs, base URL, timeout)
+  Language.php            # Enum: auto, ru, en, tr, uk, kk
+  ReviewSort.php          # Enum: relevance, newest, highest, lowest
+  MarketSort.php          # Enum: default, dpop, aprice, dprice, rating
+  MarketRegion.php        # Enum: Moscow=213, SPb=2, etc. (16 cities)
+  DealType.php            # Enum: SELL, RENT
+  PropertyCategory.php    # Enum: APARTMENT, ROOMS, HOUSE, LOT, COMMERCIAL, GARAGE
+  RealtySort.php          # Enum: RELEVANCE, DATE_DESC, PRICE, PRICE_DESC, AREA, AREA_DESC, COMMISSIONING_DATE
+  DTO/
+    Place.php             # Place/business with contacts, ratings, schedule, reviews, photos, videos
+    Review.php            # Review with author info, business reply, AI analysis, translations
+    Product.php           # Yandex Market product with pricing, seller, specs, delivery, media
+    Listing.php           # Yandex Realty listing with price, location, property details, predictions
+  Exception/
+    ApiException.php      # Base API exception
+    RateLimitException.php
+tests/
+```
+
+## Actors
+
+| Actor | ID | Description |
+|-------|----|-------------|
+| Places | `zen-studio/yandex-places-scraper` | Search Yandex Maps by keyword + location |
+| Reviews | `zen-studio/yandex-reviews-scraper` | Scrape reviews from Yandex Maps businesses |
+| Market | `zen-studio/yandex-market-scraper-parser` | Scrape products from Yandex Market |
+| Realty | `zen-studio/yandex-realty-scraper` | Scrape real estate listings from Yandex Realty |
+
+## Key Design Decisions
+
+- DTOs are immutable (readonly class with readonly properties)
+- All DTOs use named constructors (`fromArray()`) for Apify JSON mapping
+- Nullable types for optional fields from the API
+- Backed string enums for all filter/sort/language/region values
+- Empty string enum values (Auto/Default) are excluded from API input
+- Shared `runActor()` private method handles POST to run actor + fetch dataset
+- Client constructor: `new Client('apify_api_token')` or `new Client('token', new Config(...))`

README.md

@@ -2,7 +2,7 @@
 
 [English](https://github.com/Scraper-APIs/yandex-scraper-php) | **Русский**
 
-PHP-библиотека для парсинга данных Яндекса: организации и места (Яндекс Карты), отзывы (Яндекс Карты), товары (Яндекс Маркет).
+PHP-библиотека для парсинга данных Яндекса: организации и места (Яндекс Карты), отзывы (Яндекс Карты), товары (Яндекс Маркет), недвижимость (Яндекс Недвижимость).
 
 Работает через [Apify API](https://apify.com/) — запускает акторы и возвращает типизированные DTO.
 
@@ -107,6 +107,40 @@ foreach ($products as $product) {
 }
 ```
 
+### Недвижимость (Яндекс Недвижимость)
+
+```php
+use YandexParser\DealType;
+use YandexParser\PropertyCategory;
+use YandexParser\RealtySort;
+
+$listings = $client->scrapeListings(
+    location: 'Москва',
+    dealType: DealType::Sell,
+    category: PropertyCategory::Apartment,
+    maxItems: 50,
+    sort: RealtySort::PriceAsc,
+    roomsTotal: ['1', '2'],
+    options: [
+        'priceMin' => 5000000,
+        'priceMax' => 15000000,
+    ],
+);
+
+foreach ($listings as $listing) {
+    echo "{$listing->getAddress()} — {$listing->getPriceValue()} ₽" . PHP_EOL;
+    echo "Площадь: {$listing->getAreaValue()} м², этаж: {$listing->floorsOffered[0] ?? '?'}/{$listing->floorsTotal}" . PHP_EOL;
+
+    if ($listing->hasPhones()) {
+        echo "Тел: {$listing->getFirstPhone()}" . PHP_EOL;
+    }
+
+    if (!$listing->isFromOwner()) {
+        echo "Агентство: {$listing->getSellerName()}" . PHP_EOL;
+    }
+}
+```
+
 ## Перечисления
 
 | Enum | Значения |
@@ -115,6 +149,9 @@ foreach ($products as $product) {
 | `ReviewSort` | `Relevance`, `Newest`, `Highest`, `Lowest` |
 | `MarketSort` | `Default`, `Popular`, `PriceAsc`, `PriceDesc`, `Rating` |
 | `MarketRegion` | `Moscow`, `SaintPetersburg`, `Yekaterinburg`, `Kazan`, `Novosibirsk`, `NizhnyNovgorod`, `Samara`, `RostovOnDon`, `Krasnodar`, `Chelyabinsk`, `Ufa`, `Perm`, `Voronezh`, `Volgograd`, `Krasnoyarsk`, `Omsk` |
+| `DealType` | `Sell`, `Rent` |
+| `PropertyCategory` | `Apartment`, `Rooms`, `House`, `Lot`, `Commercial`, `Garage` |
+| `RealtySort` | `Relevance`, `Newest`, `PriceAsc`, `PriceDesc`, `AreaAsc`, `AreaDesc`, `CommissioningDate` |
 
 ## Конфигурация
 

src/Client.php

@@ -6,6 +6,7 @@
 
 use GuzzleHttp\Client as HttpClient;
 use GuzzleHttp\Exception\GuzzleException;
+use YandexParser\DTO\Listing;
 use YandexParser\DTO\Place;
 use YandexParser\DTO\Product;
 use YandexParser\DTO\Review;
@@ -173,6 +174,54 @@ public function scrapeProducts(
         }
     }
 
+    /**
+     * Scrape real estate listings from Yandex Realty.
+     *
+     * @param  string[]  $roomsTotal  Room count filter: ['STUDIO', '1', '2', '3', 'PLUS_4']
+     * @param  array<string, mixed>  $options  Optional (priceMin, priceMax, areaMin, areaMax, floorMin, floorMax, agents, regionId, includePhones, includePriceHistory)
+     * @return Listing[]
+     *
+     * @throws ApiException
+     * @throws RateLimitException
+     */
+    public function scrapeListings(
+        string $location = 'Москва',
+        DealType $dealType = DealType::Sell,
+        PropertyCategory $category = PropertyCategory::Apartment,
+        int $maxItems = 100,
+        RealtySort $sort = RealtySort::Relevance,
+        array $roomsTotal = [],
+        array $options = [],
+    ): array {
+        $input = [
+            'location' => $location,
+            'dealType' => $dealType->value,
+            'category' => $category->value,
+            'maxItems' => $maxItems,
+        ];
+
+        if ($sort !== RealtySort::Relevance) {
+            $input['sort'] = $sort->value;
+        }
+
+        if (count($roomsTotal) > 0) {
+            $input['roomsTotal'] = $roomsTotal;
+        }
+
+        $input = array_merge($input, $options);
+
+        try {
+            $items = $this->runActor(Config::REALTY_ACTOR_ID, $input);
+
+            return array_map(
+                static fn (array $item): Listing => Listing::fromArray($item),
+                $items
+            );
+        } catch (GuzzleException $e) {
+            $this->handleGuzzleException($e);
+        }
+    }
+
     /**
      * Run an Apify actor and return the dataset items.
      *

src/Config.php

@@ -12,6 +12,8 @@
 
     public const MARKET_ACTOR_ID = 'zen-studio/yandex-market-scraper-parser';
 
+    public const REALTY_ACTOR_ID = 'zen-studio/yandex-realty-scraper';
+
     public function __construct(
         public string $apiToken,
         public string $baseUrl = 'https://api.apify.com/v2',