PHP code example of trackstone / immo-data-php-sdk

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

trackstone / immo-data-php-sdk example snippets

use ImmoData\ImmoDataClient;
use ImmoData\Enums\RealtyType;
use ImmoData\Requests\ValuationRequest;

$client = new ImmoDataClient(apiKey: 'your-api-key');

$request = new ValuationRequest(
    longitude: 2.3488,
    latitude: 48.8534,
    realtyType: RealtyType::Apartment,
    nbRooms: 3,
    livingArea: 65.0,
);

$result = $client->valuation()->estimate($request);

echo $result->mainValuation; // 485000.0
echo $result->confidence;    // 4

use ImmoData\ImmoDataClient;

// Default (production)
$client = new ImmoDataClient(apiKey: 'your-api-key');

// Custom base URL (staging, etc.)
$client = new ImmoDataClient(
    apiKey: 'your-api-key',
    baseUrl: 'https://staging-api.immo-data.fr',
);

// Custom HTTP client (for testing or custom transport)
$client = new ImmoDataClient(
    apiKey: 'your-api-key',
    httpClient: new YourCustomHttpClient(),
);

use ImmoData\Enums\{RealtyType, Condition, Dpe};
use ImmoData\Requests\ValuationRequest;

$request = new ValuationRequest(
    longitude: 2.3488,
    latitude: 48.8534,
    realtyType: RealtyType::Apartment,
    nbRooms: 3,
    livingArea: 65.0,
    condition: Condition::Excellent,
    bathrooms: 1,
    constructionYear: 1990,
    dpe: Dpe::C,
    floor: 4,
    level: 6,
    elevator: true,
    cellar: true,
    parking: true,
);

$result = $client->valuation()->estimate($request);

$result->mainValuation;  // float — estimated price
$result->upperValuation; // float — upper bound
$result->lowerValuation; // float — lower bound
$result->confidence;     // int   — confidence score (0-5)

use ImmoData\Enums\GeoLevel;

// Simple search
$results = $client->geocode()->search('Paris');

foreach ($results as $result) {
    echo $result->label;          // "Paris, Ile-de-France"
    echo $result->geoLevel->value; // "city"
    echo $result->inseeCode;      // "75056"
    echo $result->center?->latitude;
    echo $result->center?->longitude;
}

// Filter by geographic level
$results = $client->geocode()->search(
    query: 'Lyon',
    geoLevels: [GeoLevel::City, GeoLevel::District],
    limit: 10,
);

// Region
$region = $client->geo()->region('11');
echo $region->regionName;  // "Ile-de-France"
$region->boundaries;       // GeoJsonPolygon

// Department
$department = $client->geo()->department('75');
echo $department->departmentName; // "Paris"

// City (by INSEE code)
$city = $client->geo()->city('75056');
echo $city->cityName;       // "Paris"
echo $city->postCode;       // ["75001", "75002", ...]
echo $city->districtCodes;  // ["7501", "7502", ...]

// District
$district = $client->geo()->district('7514');
echo $district->districtName;     // "Observatoire"
echo $district->subdistrictCodes; // ["751401", "751402", ...]

// Subdistrict (IRIS)
$subdistrict = $client->geo()->subdistrict('751104');
echo $subdistrict->subdistrictName;

use ImmoData\Enums\{GeoLevel, RealtyType};

// Price history for Paris apartments
$history = $client->market()->priceHistory(
    code: '75056',
    geoLevel: GeoLevel::City,
    realtyType: RealtyType::Apartment,
    startDate: '2020-01-01',
    endDate: '2024-12-31',
);

echo $history->metric; // "sqm_price"
foreach ($history->data as $point) {
    echo "{$point->period}: {$point->value} EUR/m²";
}

// Current price for a department
$price = $client->market()->currentPrice(
    code: '75',
    geoLevel: GeoLevel::Department,
    realtyType: RealtyType::Apartment,
);

echo $price->value; // 10234.5 (EUR/m², null if no data available)

use ImmoData\Enums\{GeoLevel, DurationUnit};

// History of the average sale duration for a city
$history = $client->market()->saleDurationHistory(
    code: '75114',
    geoLevel: GeoLevel::City,
    startDate: '2022-01',
    endDate: '2024-12',
    unit: DurationUnit::Days,
);

echo $history->unit; // "days"
foreach ($history->data as $point) {
    echo "{$point->period}: {$point->value} days";
}

// Current average sale duration for a department
$current = $client->market()->currentSaleDuration(
    code: '75',
    geoLevel: GeoLevel::Department,
    unit: DurationUnit::Months,
);

echo $current->unit;  // "months"
echo $current->value; // 3.0 (null if no data available)

use ImmoData\Enums\{GeoLevel, Dpe, RealtyType, DpeSortBy, SortOrder};
use ImmoData\Requests\DpeRequest;

$result = $client->dpe()->search(new DpeRequest(
    code: '75114',
    geoLevel: GeoLevel::City,
    dpeRating: [Dpe::F, Dpe::G],          // energy label (étiquette énergie)
    gesRating: [Dpe::E, Dpe::F, Dpe::G],  // climate label (étiquette climat)
    realtyType: [RealtyType::Apartment],
    sortBy: DpeSortBy::Date,
    sortOrder: SortOrder::Desc,
    size: 20,
));

echo $result->total;
foreach ($result->data as $dpe) {
    echo $dpe->dpeNumber;       // "2375E1234567A"
    echo $dpe->dpeRating;       // "D"
    echo $dpe->energyConsFinal; // 180.5 (kWh/m²/an)
    echo $dpe->location?->address?->cityName;
    echo $dpe->realty?->realtyType; // "apartment"
}

// Next page
$next = $client->dpe()->search(new DpeRequest(
    code: '75114',
    geoLevel: GeoLevel::City,
    searchAfter: $result->searchAfter,
));

// Retrieve a single DPE by its ADEME number
$dpe = $client->dpe()->get('2375E1234567A');
echo $dpe->dpeRating; // "D"

use ImmoData\Enums\{GeoLevel, ListingGroupBy, ListingMetric, ListingStat, RealtyType};
use ImmoData\Requests\ListingsStatisticsRequest;

// Ungrouped: statistics on the whole cohort
$result = $client->listings()->statistics(new ListingsStatisticsRequest(
    metrics: [ListingMetric::SquareMeterPrice, ListingMetric::Price],
    stats: [ListingStat::Mean, ListingStat::Percentile],
    realtyType: RealtyType::Apartment,
    percentiles: [10, 25, 50, 75, 90],
    code: '75114',
    geoLevel: GeoLevel::City,
));

$bucket = $result->data[0];
echo $bucket->size; // 1391 listings in the cohort
echo $bucket->metrics['squareMeterPrice']->mean; // 9500.2
foreach ($bucket->metrics['squareMeterPrice']->percentiles as $p) {
    echo "P{$p->percentile}: {$p->value}";
}

// Grouped by month
$result = $client->listings()->statistics(new ListingsStatisticsRequest(
    metrics: [ListingMetric::SquareMeterPrice],
    stats: [ListingStat::Mean],
    realtyType: RealtyType::Apartment,
    groupBy: ListingGroupBy::Month,
    code: '75114',
    geoLevel: GeoLevel::City,
));

foreach ($result->data as $bucket) {
    echo "{$bucket->key}: {$bucket->metrics['squareMeterPrice']->mean}"; // "2026-01: 9450.8"
}

// Grouped by price ranges (bounds 

use ImmoData\Exceptions\{
    ImmoDataException,
    AuthenticationException,
    ValidationException,
    InsufficientCreditsException,
    ForbiddenException,
    NotFoundException,
    RateLimitException,
    ServerException,
};

try {
    $result = $client->valuation()->estimate($request);
} catch (ValidationException $e) {
    // 400 — invalid parameters
    $errors = $e->errors(); // array of validation errors
} catch (AuthenticationException $e) {
    // 401 — invalid or missing API key
} catch (InsufficientCreditsException $e) {
    // 402 — not enough credits
} catch (ForbiddenException $e) {
    // 403 — forbidden
} catch (NotFoundException $e) {
    // 404 — resource not found
} catch (RateLimitException $e) {
    // 429 — too many requests
} catch (ServerException $e) {
    // 500/502 — server error
} catch (ImmoDataException $e) {
    // catch-all for any API error
    $e->getCode();    // HTTP status code
    $e->errorBody;    // raw error response body
}

use ImmoData\HttpClient\HttpClientInterface;

class MockHttpClient implements HttpClientInterface
{
    public function get(string $path, array $query = []): array
    {
        return match ($path) {
            '/v1/valuation' => [
                'mainValuation' => 500000,
                'upperValuation' => 550000,
                'lowerValuation' => 450000,
                'confidence' => 90,
            ],
            default => throw new \RuntimeException("Unexpected path: {$path}"),
        };
    }
}

$client = new ImmoDataClient(
    apiKey: 'test',
    httpClient: new MockHttpClient(),
);