# Rent Regulation & Rent Control API

Check rental compliance for French properties. This endpoint provides two independent services that work by **postal code** — no zone configuration needed.

## Architecture Overview

The compliance system is split into two independent services:

| Service | Purpose | Input | Coverage |
|---------|---------|-------|----------|
| **Rent Regulation** | Check if a postal code is in a "zone tendue" | Postal code | All of France |
| **Rent Control** | Get reference rent caps per m² | Address + postal code + property details | 9 French territories |

Both services are postal-code-driven. The `country_id` on places and lease types simply identifies the jurisdiction (e.g., France) — all regulation logic is handled internally via postal codes.

## Quick Examples

### Check rent regulation (zone tendue)

```bash
curl -X POST https://api.faireplace.com/api/legislative-zones/rent-regulation/check \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "postal_code": "75001" }'
```

**Response:**
```json
{
  "postal_code": "75001",
  "city_name": "Paris 1er Arrondissement",
  "is_rent_regulated": true,
  "insee_code": "75101",
  "regulation_type": {
    "type_name": "Zone tendue",
    "description": "Decree n°2023-822 of 25 August 2023",
    "rules": ["IRL-capped rent increases", "Reduced notice period (1 month)"]
  },
  "geographical_zone": {
    "zone_type": "zone_1_bis",
    "irl_cap_percentage": 3.5,
    "description": "Paris and surrounding municipalities"
  },
  "irl_info": {
    "current_quarter": "T4 2025",
    "current_value": 145.47,
    "previous_year_value": 142.06,
    "annual_increase_cap": 3.5
  }
}
```

### Check rent control compliance

```bash
curl -X POST https://api.faireplace.com/api/legislative-zones/rent-control/check \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "24 rue du Faubourg Saint-Antoine",
    "postal_code": "75012",
    "room_count": 2,
    "surface_area": 45.0,
    "construction_period": "1946_1970",
    "is_furnished": false,
    "proposed_rent": 900.0
  }'
```

**Response:**
```json
{
  "territory": "Paris",
  "address": "24 rue du Faubourg Saint-Antoine",
  "administrative_quarter": "Quinze-Vingts",
  "reference_rent_data": {
    "reference_rent": 22.80,
    "reference_rent_increased": 27.36,
    "reference_rent_decreased": 19.38
  },
  "proposed_rent_per_sqm": 20.00,
  "is_compliant": true,
  "compliance_status": "Compliant"
}
```

---

## Rent Regulation Endpoints

### Check rent regulation by postal code
**POST** `/api/legislative-zones/rent-regulation/check`

Determines whether a postal code falls in a "zone tendue" (tight housing market). Returns IRL (Indice de Reference des Loyers) data and applicable rules.

**Request:**
```json
{ "postal_code": "69001" }
```

### Get regulation data by INSEE code
**GET** `/api/legislative-zones/rent-regulation/zone/{insee_code}`

---

## Rent Control Endpoints

Rent control (encadrement des loyers) provides reference rent caps per m². Currently supported in **9 French territories**.

### Check rent control compliance
**POST** `/api/legislative-zones/rent-control/check`

**Request:**
```json
{
  "address": "15 rue de la République",
  "postal_code": "69001",
  "room_count": 3,
  "surface_area": 65.0,
  "construction_period": "1971_1990",
  "is_furnished": true,
  "proposed_rent": 1200.0
}
```

### Get administrative quarter
**GET** `/api/legislative-zones/rent-control/quarter?address={address}&postal_code={postal_code}`

Resolves an address to its administrative quarter (used by rent control).

### Get reference rent
**GET** `/api/legislative-zones/rent-control/reference-rent?quarter={quarter}&room_count={n}&construction_period={period}&is_furnished={bool}&year={year}`

Returns reference rent data for a given quarter and property parameters.

### List supported territories
**GET** `/api/legislative-zones/rent-control/territories`

Returns the list of territories where rent control is active.

**Response:**
```json
{
  "territories": [
    "Paris", "Lyon", "Lille", "Bordeaux", "Montpellier",
    "Grenoble", "Est Ensemble", "Plaine Commune", "Pays Basque"
  ]
}
```

---

## Construction Periods

| Value | Period |
|-------|--------|
| `before_1946` | Before 1946 |
| `1946_1970` | 1946 to 1970 |
| `1971_1990` | 1971 to 1990 |
| `1991_2005` | 1991 to 2005 |
| `after_2005` | After 2005 |
| `after_1990` | After 1990 |

---

## Country Reference

Places and lease types reference a `country_id` (UUID) that points to the `country` table. This simple reference identifies the jurisdiction for a property.

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "code": "FR",
  "name": "France",
  "is_active": true
}
```

Currently supported: **France (FR)**. Additional countries will be added as the platform expands.

---

## How It Fits Together

1. **Create a place** with `country_id` pointing to France
2. **Create a lease** for an estate in that place
3. **Check compliance** using the rent-regulation and rent-control endpoints with the property's postal code
4. The lease compliance checker (`POST /api/leases/{id}/compliance`) automatically runs both checks

---

## French Legal Context

### Zone Tendue (Tight Market Zone)
- Defined by Decree n°2023-822
- Cities with housing shortage (1,149 municipalities)
- Applies IRL-capped rent increases and reduced notice periods

### Encadrement des Loyers (Rent Control)
- Municipal rent control system in 9 territories
- Maximum rent per m² by quarter, room count, construction period, and furnished status
- Applies to new leases and renewals

## Data freshness

| Data type | Update frequency | Source |
|-----------|-----------------|--------|
| Zone tendue list | When decree is updated (~annually) | Journal Officiel |
| IRL index | Quarterly (published by INSEE) | INSEE |
| Reference rents (encadrement) | Annually per territory | Prefectoral decrees (DRIHL, etc.) |
| Supported territories | As new cities adopt rent control | Municipal decisions |

FairePlace monitors official publications and updates its data within 5 business days of publication. The `last_updated` field in API responses indicates when the data was last refreshed.

> **Tip:** Use `GET /api/legislative-zones/rent-control/territories` to see which territories are currently supported and their last update date.

---

## Error Responses

**400 Bad Request**
```json
{
  "error": "ValidationError",
  "message": "Postal code is required"
}
```

**404 Not Found**
```json
{
  "error": "NotFound",
  "message": "No rent control data available for this territory"
}
```