# French Real-estate Market

Summarizes local French property transaction prices and yearly trends from geolocated DVF data.

## Endpoint

- Method: `POST`
- URL: `https://api.helpmyagent.com/v1/real-estate/fr/market`
- Price: `0.020 USD` / call

## Machine discovery

- llms.txt: https://helpmyagent.com/llms.txt
- OpenAPI 3.1: https://api.helpmyagent.com/openapi.json
- capabilities.json: https://helpmyagent.com/capabilities.json
- MCP: https://helpmyagent.com/mcp
- RFC 9727: https://helpmyagent.com/.well-known/api-catalog
- pricing.json: https://helpmyagent.com/pricing.json
- x402: https://helpmyagent.com/.well-known/x402
- x402-service.json: https://helpmyagent.com/.well-known/x402-service.json
- Health status: https://helpmyagent.com/health

## x402 payment methods

- USDC on `eip155:8453`
- RLUSD on `xrpl:0`

## Coverage

FR

## Use when

- Summarize a French local property market from recorded transactions.

## Avoid when

- Do not use as a listing-price index or a certified appraisal.

## Limitations

- Statistics use up to 200 geolocated DVF single-dwelling mutations per year and residential property type; VEFA/new and professional-use mutations are excluded, with truncation exposed explicitly.
- DVF does not cover Alsace, Moselle or Mayotte; requests in those areas therefore return an empty result.

## Example queries

- Summarize the apartment market in INSEE commune 75112.

## Freshness

```json
{
    "mode": "source_dependent"
}
```

## Sources

- [DVF géolocalisées - data.gouv.fr](https://files.data.gouv.fr/geo-dvf/latest/csv/)
- [API Géoplateforme - Géocodage (BAN/IGN)](https://data.geopf.fr/geocodage/search)

## Input schema

```json
{
    "type": "object",
    "properties": {
        "address": {
            "type": "string",
            "minLength": 5,
            "maxLength": 250,
            "description": "Optional value for “address” as defined by this API contract. (minimum length 5; maximum length 250)."
        },
        "code_insee": {
            "type": "string",
            "pattern": "^(?:[0-9]{5}|2[ABab][0-9]{3})$",
            "description": "Optional value for “code insee” as defined by this API contract."
        },
        "property_type": {
            "type": "string",
            "enum": [
                "all",
                "house",
                "apartment"
            ],
            "default": "all",
            "description": "Optional value for “property type” as defined by this API contract. (default all; allowed values: all, house, apartment)."
        },
        "radius_m": {
            "type": "integer",
            "minimum": 100,
            "maximum": 650,
            "default": 650,
            "description": "Optional value for “radius m” as defined by this API contract. (minimum 100; maximum 650; default 650)."
        },
        "lookback_years": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5,
            "default": 5,
            "description": "Optional value for “lookback years” as defined by this API contract. (minimum 1; maximum 5; default 5)."
        }
    },
    "anyOf": [
        {
            "required": [
                "address"
            ]
        },
        {
            "required": [
                "code_insee"
            ]
        }
    ],
    "additionalProperties": false,
    "description": "Structured input parameters for the real-estate/fr/market API."
}
```

## Output schema

```json
{
    "type": "object",
    "properties": {
        "location": {
            "type": "object",
            "properties": {
                "code_insee": {
                    "type": [
                        "string",
                        "null"
                    ],
                    "description": "Structured value returned for “code insee” as defined by this API contract."
                },
                "address": {
                    "type": [
                        "string",
                        "null"
                    ],
                    "description": "Structured value returned for “address” as defined by this API contract."
                },
                "normalized_address": {
                    "type": [
                        "string",
                        "null"
                    ],
                    "description": "Structured value returned for “normalized address” as defined by this API contract."
                },
                "postcode": {
                    "type": [
                        "string",
                        "null"
                    ],
                    "description": "Structured value returned for “postcode” as defined by this API contract."
                },
                "city": {
                    "type": [
                        "string",
                        "null"
                    ],
                    "description": "Structured value returned for “city” as defined by this API contract."
                },
                "ban_id": {
                    "type": [
                        "string",
                        "null"
                    ],
                    "description": "Structured value returned for “ban id” as defined by this API contract."
                },
                "geocoding_score": {
                    "type": [
                        "number",
                        "integer",
                        "null"
                    ],
                    "description": "Structured value returned for “geocoding score” as defined by this API contract."
                },
                "longitude": {
                    "type": [
                        "number",
                        "integer",
                        "null"
                    ],
                    "description": "Structured value returned for “longitude” as defined by this API contract."
                },
                "latitude": {
                    "type": [
                        "number",
                        "integer",
                        "null"
                    ],
                    "description": "Structured value returned for “latitude” as defined by this API contract."
                }
            },
            "required": [
                "code_insee",
                "address",
                "normalized_address",
                "postcode",
                "city",
                "ban_id",
                "geocoding_score",
                "longitude",
                "latitude"
            ],
            "additionalProperties": false,
            "description": "Structured value returned for “location” as defined by this API contract."
        },
        "coverage_scope": {
            "type": "string",
            "enum": [
                "radius",
                "commune"
            ],
            "description": "Structured value returned for “coverage scope” as defined by this API contract. (allowed values: radius, commune)."
        },
        "radius_m": {
            "type": [
                "integer",
                "null"
            ],
            "description": "Structured value returned for “radius m” as defined by this API contract."
        },
        "property_type": {
            "type": "string",
            "description": "Structured value returned for “property type” as defined by this API contract."
        },
        "lookback_years": {
            "type": "integer",
            "description": "Structured value returned for “lookback years” as defined by this API contract."
        },
        "source_status": {
            "type": "string",
            "enum": [
                "ok"
            ],
            "description": "Availability status of the relevant upstream public source. (allowed values: ok)."
        },
        "source_total_count": {
            "type": [
                "integer",
                "null"
            ],
            "description": "Structured value returned for “source total count” as defined by this API contract."
        },
        "sampled_count": {
            "type": [
                "integer",
                "null"
            ],
            "description": "Structured value returned for “sampled count” as defined by this API contract."
        },
        "sample_truncated": {
            "type": [
                "boolean",
                "null"
            ],
            "description": "Structured value returned for “sample truncated” as defined by this API contract."
        },
        "summary": {
            "type": "object",
            "properties": {
                "median_price_per_m2": {
                    "type": [
                        "number",
                        "integer",
                        "null"
                    ],
                    "description": "Structured value returned for “median price per m2” as defined by this API contract."
                },
                "p25_price_per_m2": {
                    "type": [
                        "number",
                        "integer",
                        "null"
                    ],
                    "description": "Structured value returned for “p25 price per m2” as defined by this API contract."
                },
                "p75_price_per_m2": {
                    "type": [
                        "number",
                        "integer",
                        "null"
                    ],
                    "description": "Structured value returned for “p75 price per m2” as defined by this API contract."
                },
                "median_transaction_amount": {
                    "type": [
                        "number",
                        "integer",
                        "null"
                    ],
                    "description": "Structured value returned for “median transaction amount” as defined by this API contract."
                }
            },
            "required": [
                "median_price_per_m2",
                "p25_price_per_m2",
                "p75_price_per_m2",
                "median_transaction_amount"
            ],
            "additionalProperties": false,
            "description": "Compact derived summary of the returned records."
        },
        "yearly": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "year": {
                        "type": "string",
                        "description": "Structured value returned for “year” as defined by this API contract."
                    },
                    "transactions_count": {
                        "type": "integer",
                        "description": "Structured value returned for “transactions count” as defined by this API contract."
                    },
                    "median_price_per_m2": {
                        "type": [
                            "number",
                            "integer",
                            "null"
                        ],
                        "description": "Structured value returned for “median price per m2” as defined by this API contract."
                    }
                },
                "required": [
                    "year",
                    "transactions_count",
                    "median_price_per_m2"
                ],
                "additionalProperties": false
            },
            "description": "Structured value returned for “yearly” as defined by this API contract."
        },
        "generated_at": {
            "type": "string",
            "description": "UTC timestamp at which this derived result was generated."
        },
        "limitations": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "description": "Known interpretation, source-coverage or freshness limitations for this result."
        }
    },
    "required": [
        "location",
        "coverage_scope",
        "radius_m",
        "property_type",
        "lookback_years",
        "source_status",
        "source_total_count",
        "sampled_count",
        "sample_truncated",
        "summary",
        "yearly",
        "generated_at"
    ],
    "additionalProperties": false,
    "description": "Structured result returned by the real-estate/fr/market API."
}
```

## Request example

```json
{
    "code_insee": "75112",
    "property_type": "apartment",
    "lookback_years": 5
}
```

## Billing policy

```json
{
    "charge_on": "valid_result",
    "no_charge_on_empty_result": true,
    "no_charge_on_error": true
}
```