One upstream lookup per request. Resolve free text to zone ids with the locations endpoint first and pass them as zone_ids — search deliberately does not resolve place names for you, because that would cost a second upstream lookup inside one billable request. zone_ids is the only location identifier that filters: there is no location_id parameter, and an INSEE or postal code passed in its place is accepted and silently ignored, which returns unfiltered national stock instead of an error. Each ad is normalized so price reads as min/max/currency/disclosed with unit "total" — a euro amount for the whole property — and ads whose transactionType does not match the request are removed, because the upstream filter expression does not reliably hold. property_type cannot be combined with transaction_type=new_build: new build is expressed as a programme filter, so the pair would be accepted and then ignored. The upstream total is not published: it is a global counter rather than a result count (976 427 on a two-ad Paris page), so returnedCount is the number of ads in the response and from/perPage are the paging echo.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
This endpoint has no required query parameters.
20 optional filters available.
string
Optional
buy (achat), rent (location), or new_build (neuf, which searches new-build programmes).
rent
string[]
Optional
Repeatable zone ids from the locations endpoint. -7444 is Paris: the captured search in tests/Fixtures/BienIci/search.json is exactly that zone id and returns Paris ads. Zone ids are hyphenated strings upstream; plain numbers are accepted and normalized, but the locations endpoint returns them as strings.
["-7444"]
string[]
Optional
Repeatable 5-digit postal codes applied after the search, for exact postal-code matching.
example
number
Optional
Minimum price.
10
number
Optional
Maximum price.
10
number
Optional
Minimum floor area in m².
10
number
Optional
Maximum floor area in m².
10
integer
Optional
Minimum bedrooms (chambres), excluding the living room.
10
integer
Optional
Maximum bedrooms (chambres).
10
integer
Optional
Minimum total rooms (pièces).
10
integer
Optional
Maximum total rooms (pièces).
10
number
Optional
Minimum land area in m².
10
number
Optional
Maximum land area in m².
10
string
Optional
Energy performance letter, for example D.
example
boolean
Optional
Only ads currently on the market.
true
boolean
Optional
Only new properties.
true
string
Optional
Sort order key. Only publicationDate is offered; the upstream default relevance sort mixes buy ads into rent results.
relevance
string
Optional
asc or desc, default desc.
example
integer
Optional
1-based page. page and size must not address a window beyond 2500 results.
1
integer
Optional
Ads per page, 1 to 500.
2
Request Examples
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://scrappa.co/api/bienici/search?transaction_type=rent&zone_ids%5B0%5D=-7444&size=2",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: YOUR_API_KEY_HERE"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
<?php
use Illuminate\Support\Facades\Http;
$response = Http::timeout(30)
->withHeaders(['x-api-key' => 'YOUR_API_KEY_HERE'])
->get('https://scrappa.co/api/bienici/search?transaction_type=rent&zone_ids%5B0%5D=-7444&size=2');
if ($response->successful()) {
echo $response->body();
} else {
echo "Error: " . $response->status();
}
const options = {
method: 'GET',
headers: {
'x-api-key': 'YOUR_API_KEY_HERE'
}
};
fetch('https://scrappa.co/api/bienici/search?transaction_type=rent&zone_ids%5B0%5D=-7444&size=2', options)
.then(response => {
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
return response.text();
})
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
const axios = require('axios');
const options = {
method: 'GET',
url: 'https://scrappa.co/api/bienici/search?transaction_type=rent&zone_ids%5B0%5D=-7444&size=2',
headers: {
x-api-key: 'YOUR_API_KEY_HERE',
}
};
try {
const response = await axios(options);
console.log(response.data);
} catch (error) {
console.error('Error:', error.message);
}
require 'net/http'
require 'uri'
uri = URI.parse("https://scrappa.co/api/bienici/search?transaction_type=rent&zone_ids%5B0%5D=-7444&size=2")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == 'https'
request = Net::HTTP::Get.new(uri.request_uri)
request['x-api-key'] = 'YOUR_API_KEY_HERE'
begin
response = http.request(request)
puts response.body
rescue => e
puts "Error: #{e.message}"
end
import http.client
import json
conn = http.client.HTTPSConnection("scrappa.co")
headers = {
'x-api-key': 'YOUR_API_KEY_HERE',
}
try:
conn.request("GET", "/api/bienici/search?transaction_type=rent&zone_ids%5B0%5D=-7444&size=2", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
except Exception as e:
print(f"Error: {e}")
finally:
conn.close()
import requests
headers = {
'x-api-key': 'YOUR_API_KEY_HERE',
}
try:
response = requests.get('https://scrappa.co/api/bienici/search?transaction_type=rent&zone_ids%5B0%5D=-7444&size=2', headers=headers)
response.raise_for_status()
print(response.text)
except requests.exceptions.RequestException as e:
print(f"Error: {e}")
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import java.io.IOException;
public class ApiExample {
public static void main(String[] args) {
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://scrappa.co/api/bienici/search?transaction_type=rent&zone_ids%5B0%5D=-7444&size=2")
.addHeader("x-api-key", "YOUR_API_KEY_HERE")
.build();
try (Response response = client.newCall(request).execute()) {
if (response.isSuccessful()) {
System.out.println(response.body().string());
} else {
System.out.println("Error: " + response.code());
}
} catch (IOException e) {
System.out.println("Error: " + e.getMessage());
}
}
}
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
client := &http.Client{}
req, err := http.NewRequest("GET", "https://scrappa.co/api/bienici/search?transaction_type=rent&zone_ids%5B0%5D=-7444&size=2", nil)
if err != nil {
fmt.Println("Error creating request:", err)
return
}
req.Header.Set("x-api-key", "YOUR_API_KEY_HERE")
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error making request:", err)
return
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
fmt.Println("Error reading response:", err)
return
}
fmt.Println(string(body))
}
#!/bin/bash
curl -X GET \
-H "x-api-key: YOUR_API_KEY_HERE" \
"https://scrappa.co/api/bienici/search?transaction_type=rent&zone_ids%5B0%5D=-7444&size=2"
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY_HERE");
try
{
var response = await client.SendAsync(new HttpRequestMessage(HttpMethod.Get, "https://scrappa.co/api/bienici/search?transaction_type=rent&zone_ids%5B0%5D=-7444&size=2"));
var content = await response.Content.ReadAsStringAsync();
Console.WriteLine(content);
}
catch (Exception ex)
{
Console.WriteLine($"Error: {ex.Message}");
}
}
}
import axios from 'axios';
async function run(): Promise<void> {
try {
const response = await axios({
method: 'GET',
url: 'https://scrappa.co/api/bienici/search?transaction_type=rent&zone_ids%5B0%5D=-7444&size=2',
headers: {
'x-api-key': 'YOUR_API_KEY_HERE',
},
});
console.log(response.data);
} catch (error) {
console.error('Error:', error);
}
}
void run();
use reqwest::Client;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Client::new();
let response = client
.get("https://scrappa.co/api/bienici/search?transaction_type=rent&zone_ids%5B0%5D=-7444&size=2")
.header("x-api-key", "YOUR_API_KEY_HERE")
.send()
.await?;
println!("{}", response.text().await?);
Ok(())
}
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
success
data
meta
{
"success": true,
"data": {
"realEstateAds": [
{
"id": "ag750725-49688129",
"reference": "602996",
"transactionType": "rent",
"propertyType": "flat",
"price": {
"min": null,
"max": null,
"currency": null,
"disclosed": false,
"unit": "total"
},
"surfaceArea": 40,
"roomsQuantity": 2,
"city": "Paris",
"postalCode": "75007"
},
{
"id": "snpi-1101655",
"reference": "918",
"transactionType": "rent",
"propertyType": "flat",
"price": {
"min": null,
"max": null,
"currency": null,
"disclosed": false,
"unit": "total"
},
"surfaceArea": 92,
"roomsQuantity": 3,
"bedroomsQuantity": 2,
"city": "Paris",
"postalCode": "75015"
}
],
"returnedCount": 2,
"from": 0,
"perPage": 2
},
"meta": {
"endpoint_family": "search"
}
}
Errors
Handle these documented responses before retrying or showing customer-facing failures.
Not Found
The requested house was not found. This response is not billable.
Validation Error
A public parameter is invalid. This response is not billable.
Service Unavailable
The service could not obtain a complete result. This response is not billable.
Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.