Aller au contenu

🏠 Guide Complet - API Logements Boaz Housing

📋 Introduction

Ce guide vous explique comment ajouter des logements à la plateforme Boaz Housing via des requêtes API, même si vous n'avez jamais programmé !

Ce que vous allez pouvoir faire : - Ajouter des logements automatiquement via script - Vérifier si un logement existe déjà - Lister les logements existants - Modifier ou supprimer des logements

🌐 Informations de Base

URL de l'API

1
https://api-housing.boaz-study.tech/api/logements/

Méthodes HTTP

  • POST : Créer un nouveau logement
  • GET : Récupérer des logements
  • PUT : Modifier un logement existant
  • DELETE : Supprimer un logement

🏗️ Structure d'un Logement

Champs Obligatoires ✅

1
2
3
4
5
6
7
{
  "titre": "Appartement 2 pièces centre-ville",
  "adresse": "15 Rue de la Paix, Paris",
  "ville": "Paris",
  "code_postal": "75001",
  "loyer": 850.00
}

Champs Optionnels ⚪

1
2
3
4
5
6
7
8
9
{
  "description": "Appartement lumineux avec balcon, proche transports",
  "pays": "France",
  "montant_charges": 80.00,
  "coordonnees_gps": "long:2.3522,lat:48.8566,alt:0",
  "cood_gps_standart": "48.8566,2.3522",
  "statut": "disponible",
  "author_id": 123
}

Exemple Complet

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "titre": "Appartement 2 pièces centre-ville",
  "description": "Appartement lumineux avec balcon, proche transports",
  "adresse": "15 Rue de la Paix, Paris",
  "ville": "Paris",
  "code_postal": "75001",
  "pays": "France",
  "loyer": 850.00,
  "montant_charges": 80.00,
  "coordonnees_gps": "long:2.3522,lat:48.8566,alt:0",
  "cood_gps_standart": "48.8566,2.3522",
  "statut": "disponible"
}

📝 Règles de Validation

Titre

  • Minimum : 3 caractères
  • Maximum : 200 caractères
  • Exemples valides :
    • ✅ "Studio meublé"
    • ✅ "Appartement 3 pièces avec jardin"
    • ❌ "T2" (trop court)

Adresse

  • Minimum : 5 caractères
  • Maximum : 500 caractères
  • Exemples valides :
    • ✅ "15 Rue de la Paix, 75001 Paris"
    • ✅ "123 Avenue des Champs-Élysées"

Ville

  • Minimum : 2 caractères
  • Maximum : 100 caractères
  • Format : Lettres, espaces, tirets, apostrophes uniquement
  • Exemples valides :
    • ✅ "Paris"
    • ✅ "Saint-Denis"
    • ✅ "L'Haÿ-les-Roses"
    • ❌ "Paris123" (chiffres interdits)

Code Postal

  • Formats acceptés :
    • 🇫🇷 France : 75001, 13000
    • 🇧🇪 Belgique : 1000, 2000
    • 🇨🇭 Suisse : 1200, 8000
    • 🇨🇦 Canada : H3A 1A1
    • 🇺🇸 USA : 90210, 10001-1234

Loyer

  • Minimum : 0.01€
  • Maximum : 50,000€
  • Format : Nombre décimal (ex: 850.50)

Charges

  • Minimum : 0€
  • Maximum : 10,000€
  • Défaut : 0€ si non spécifié

Statut

  • "disponible" (défaut)
  • "occupe"
  • "maintenance"

Pays

Pays supportés : - France, Belgique, Suisse, Luxembourg - Canada, USA, Etats-Unis - Allemagne, Italie, Espagne

🚀 Utilisation Pratique

1. Créer un Logement

Requête cURL (Terminal)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
curl -X POST "https://api-housing.boaz-study.tech/api/logements/" \
  -H "Content-Type: application/json" \
  -d '{
    "titre": "Studio meublé centre-ville",
    "description": "Studio lumineux de 25m², entièrement meublé",
    "adresse": "25 Boulevard Saint-Michel, 75005 Paris",
    "ville": "Paris",
    "code_postal": "75005",
    "pays": "France",
    "loyer": 950.00,
    "montant_charges": 120.00,
    "statut": "disponible"
  }'

Réponse de Succès

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "id": 456,
  "titre": "Studio meublé centre-ville",
  "description": "Studio lumineux de 25m², entièrement meublé",
  "adresse": "25 Boulevard Saint-Michel, 75005 Paris",
  "ville": "Paris",
  "code_postal": "75005",
  "pays": "France",
  "loyer": 950.00,
  "montant_charges": 120.00,
  "montant_total": 1070.00,
  "statut": "disponible",
  "author_id": 2,
  "author": {
    "id": 2,
    "nom": "Dupont",
    "prenom": "Jean",
    "email": "jean.dupont@example.com",
    "role": "ADMIN"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": null
}

2. Vérifier si un Logement Existe

1
curl "https://api-housing.boaz-study.tech/api/logements/check-existence?adresse=25%20Boulevard%20Saint-Michel&ville=Paris"

Réponse si Existe

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "exists": true,
  "logement": {
    "id": 456,
    "titre": "Studio meublé centre-ville",
    "adresse": "25 Boulevard Saint-Michel, 75005 Paris",
    "ville": "Paris",
    "loyer": 950.00,
    "montant_charges": 120.00,
    "montant_total": 1070.00,
    "statut": "disponible"
  }
}

Réponse si N'existe Pas

1
2
3
4
{
  "exists": false,
  "logement": null
}

3. Lister Tous les Logements

1
curl "https://api-housing.boaz-study.tech/api/logements/"

4. Lister Logements Disponibles Uniquement

1
curl "https://api-housing.boaz-study.tech/api/logements/disponibles"

5. Lister Logements du Parc (Non-automatiques)

1
curl "https://api-housing.boaz-study.tech/api/logements/parc"

6. Récupérer un Logement Spécifique

1
curl "https://api-housing.boaz-study.tech/api/logements/456"

7. Modifier un Logement

1
2
3
4
5
6
curl -X PUT "https://api-housing.boaz-study.tech/api/logements/456" \
  -H "Content-Type: application/json" \
  -d '{
    "loyer": 980.00,
    "description": "Studio lumineux de 25m², entièrement rénové"
  }'

8. Supprimer un Logement

1
curl -X DELETE "https://api-housing.boaz-study.tech/api/logements/456"

🐍 Scripts Python Prêts à Utiliser

Script 1 : Ajouter un Logement Simple

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
import requests
import json

# Configuration
API_URL = "https://api-housing.boaz-study.tech/api/logements/"

# Données du logement
logement_data = {
    "titre": "Appartement 3 pièces familial",
    "description": "Appartement spacieux avec 2 chambres, salon et cuisine équipée",
    "adresse": "45 Avenue de la République, 75011 Paris",
    "ville": "Paris",
    "code_postal": "75011",
    "pays": "France",
    "loyer": 1200.00,
    "montant_charges": 150.00,
    "statut": "disponible"
}

# Envoi de la requête
try:
    response = requests.post(
        API_URL,
        headers={"Content-Type": "application/json"},
        json=logement_data
    )

    if response.status_code == 200:
        logement_cree = response.json()
        print(f"✅ Logement créé avec succès !")
        print(f"ID: {logement_cree['id']}")
        print(f"Titre: {logement_cree['titre']}")
        print(f"Montant total: {logement_cree['montant_total']}€")
    else:
        print(f"❌ Erreur: {response.status_code}")
        print(f"Message: {response.text}")

except Exception as e:
    print(f"❌ Erreur de connexion: {e}")

Script 2 : Ajouter Plusieurs Logements

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
import requests
import json
import time

# Configuration
API_URL = "https://api-housing.boaz-study.tech/api/logements/"

# Liste de logements à ajouter
logements = [
    {
        "titre": "Studio étudiant Belleville",
        "description": "Petit studio parfait pour étudiant, quartier vivant",
        "adresse": "12 Rue de Belleville, 75020 Paris",
        "ville": "Paris",
        "code_postal": "75020",
        "loyer": 650.00,
        "montant_charges": 80.00
    },
    {
        "titre": "T2 moderne Montparnasse",
        "description": "Appartement rénové avec balcon, proche gare",
        "adresse": "33 Boulevard Montparnasse, 75015 Paris",
        "ville": "Paris",
        "code_postal": "75015",
        "loyer": 1050.00,
        "montant_charges": 120.00
    },
    {
        "titre": "Maison individuelle Banlieue",
        "description": "Maison 4 pièces avec jardin, parking privé",
        "adresse": "18 Rue des Lilas, 94100 Saint-Maur-des-Fossés",
        "ville": "Saint-Maur-des-Fossés",
        "code_postal": "94100",
        "loyer": 1800.00,
        "montant_charges": 200.00
    }
]

# Fonction pour ajouter un logement
def ajouter_logement(logement_data):
    try:
        # Vérifier d'abord si le logement existe
        check_url = f"https://api-housing.boaz-study.tech/api/logements/check-existence"
        check_params = {
            "adresse": logement_data["adresse"],
            "ville": logement_data["ville"]
        }

        check_response = requests.get(check_url, params=check_params)
        if check_response.status_code == 200 and check_response.json().get("exists"):
            print(f"⚠️  Logement déjà existant: {logement_data['titre']}")
            return False

        # Créer le logement
        response = requests.post(
            API_URL,
            headers={"Content-Type": "application/json"},
            json=logement_data
        )

        if response.status_code == 200:
            logement = response.json()
            print(f"✅ Créé: {logement['titre']} (ID: {logement['id']})")
            return True
        else:
            print(f"❌ Erreur pour '{logement_data['titre']}': {response.text}")
            return False

    except Exception as e:
        print(f"❌ Erreur connexion pour '{logement_data['titre']}': {e}")
        return False

# Traitement de la liste
print(f"🏠 Ajout de {len(logements)} logements...")
print("-" * 50)

succes = 0
for i, logement in enumerate(logements, 1):
    print(f"[{i}/{len(logements)}] {logement['titre']}")

    if ajouter_logement(logement):
        succes += 1

    # Pause entre les requêtes pour éviter la surcharge
    time.sleep(0.5)

print("-" * 50)
print(f"🎯 Résultat: {succes}/{len(logements)} logements ajoutés avec succès")

Script 3 : Ajouter Logements depuis Fichier JSON

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
import requests
import json
import time

# Configuration
API_URL = "https://api-housing.boaz-study.tech/api/logements/"
JSON_FILE = "logements.json"  # Nom de votre fichier JSON

def lire_logements_json(fichier_json):
    """Lit les logements depuis un fichier JSON"""
    try:
        with open(fichier_json, 'r', encoding='utf-8') as file:
            logements = json.load(file)

        if not isinstance(logements, list):
            print(f"❌ Le fichier JSON doit contenir une liste de logements")
            return []

        print(f"📁 {len(logements)} logements lus depuis {fichier_json}")
        return logements

    except FileNotFoundError:
        print(f"❌ Fichier {fichier_json} introuvable")
        return []
    except json.JSONDecodeError as e:
        print(f"❌ Erreur format JSON: {e}")
        return []
    except Exception as e:
        print(f"❌ Erreur lecture JSON: {e}")
        return []

def verifier_existence_logement(adresse, ville):
    """Vérifie si un logement existe déjà"""
    try:
        check_url = "https://api-housing.boaz-study.tech/api/logements/check-existence"
        params = {"adresse": adresse, "ville": ville}
        response = requests.get(check_url, params=params, timeout=10)

        if response.status_code == 200:
            return response.json().get("exists", False)
        return False
    except:
        return False

def ajouter_logement_api(logement_data):
    """Ajoute un logement via l'API"""
    try:
        response = requests.post(
            API_URL,
            headers={"Content-Type": "application/json"},
            json=logement_data,
            timeout=15
        )

        if response.status_code == 200:
            return True, response.json()
        else:
            try:
                error_details = response.json()
                return False, f"Erreur {response.status_code}: {error_details.get('detail', response.text)}"
            except:
                return False, f"Erreur {response.status_code}: {response.text}"

    except Exception as e:
        return False, str(e)

# Programme principal
if __name__ == "__main__":
    print("🏠 Import de logements depuis JSON")
    print("=" * 50)

    # Lire le fichier JSON
    logements = lire_logements_json(JSON_FILE)

    if not logements:
        print("❌ Aucun logement à traiter")
        exit()

    # Traiter chaque logement
    succes = 0
    echecs = 0
    doublons = 0

    for i, logement in enumerate(logements, 1):
        titre = logement.get('titre', 'Sans titre')
        print(f"\n[{i}/{len(logements)}] {titre}")

        # Vérifier l'existence
        if verifier_existence_logement(logement.get('adresse'), logement.get('ville')):
            print(f"   ⚠️  Logement déjà existant - Ignoré")
            doublons += 1
            continue

        # Créer le logement
        succes_api, resultat = ajouter_logement_api(logement)

        if succes_api:
            print(f"   ✅ Créé avec l'ID: {resultat.get('id')}")
            print(f"      💰 Total: {resultat.get('montant_total')}€")
            succes += 1
        else:
            print(f"   ❌ Échec: {resultat}")
            echecs += 1

        # Pause entre requêtes
        time.sleep(0.5)

    print("\n" + "=" * 50)
    print(f"🎯 RÉSULTAT FINAL:")
    print(f"   ✅ Succès: {succes}")
    print(f"   ❌ Échecs: {echecs}")
    print(f"   ⚠️  Doublons ignorés: {doublons}")
    print(f"   📊 Total: {len(logements)}")

Format du fichier JSON (logements.json) : 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
[
  {
    "titre": "Studio centre-ville",
    "description": "Studio meublé 20m²",
    "adresse": "15 Rue du Commerce, Lyon",
    "ville": "Lyon",
    "code_postal": "69002",
    "pays": "France",
    "loyer": 720.00,
    "montant_charges": 90.00,
    "statut": "disponible"
  },
  {
    "titre": "T2 Belleville",
    "description": "Appartement lumineux",
    "adresse": "8 Boulevard de Belleville, Paris",
    "ville": "Paris",
    "code_postal": "75020",
    "pays": "France",
    "loyer": 980.00,
    "montant_charges": 110.00,
    "statut": "disponible"
  }
]

⚠️ Gestion des Erreurs

Erreurs Communes

400 - Données Invalides

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "loyer"],
      "msg": "Le loyer doit être supérieur à 0",
      "input": 0
    }
  ]
}

409 - Logement Déjà Existant

1
2
3
{
  "detail": "Un logement existe déjà à cette adresse: 15 Rue de la Paix, Paris"
}

422 - Format JSON Invalide

1
2
3
4
5
6
7
8
9
{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "titre"],
      "msg": "Field required"
    }
  ]
}

Codes de Réponse HTTP

  • 200 : Succès
  • 400 : Données invalides
  • 404 : Logement non trouvé
  • 409 : Conflit (logement déjà existant)
  • 422 : Erreur de validation
  • 500 : Erreur serveur

🔧 Outils Recommandés

1. Pour Tester (Débutants)

  • Postman : Interface graphique pour tester les API
  • Insomnia : Alternative à Postman
  • curl : Outil en ligne de commande (inclus sur Mac/Linux)

2. Pour Automatiser

  • Python + requests : Scripts personnalisés
  • Node.js + axios : Pour JavaScript
  • PowerShell : Sur Windows

3. Formats de Données

  • JSON : Format natif et recommandé de l'API ⭐
  • Structures de données : Arrays et objects JavaScript/Python
  • Éditeurs JSON : Visual Studio Code, JSONLint pour validation

📞 Support et Assistance

Swagger UI (Documentation Interactive)

1
https://api-housing.boaz-study.tech/docs

Contact Technique

Ressources Utiles

✨ Conseils Pro

1. Optimisation Performance

  • Ajoutez une pause de 0.5s entre les requêtes
  • Vérifiez l'existence avant de créer
  • Utilisez des lots de 50 logements maximum

2. Bonnes Pratiques

  • Validez vos données avant envoi
  • Gardez une sauvegarde de vos fichiers
  • Testez avec 1-2 logements d'abord
  • Surveillez les logs d'erreur

3. Sécurité

  • Ne partagez jamais vos scripts avec des clés
  • Utilisez HTTPS uniquement
  • Validez toujours les adresses

🎯 Exemples Rapides

Ajouter UN logement rapidement :

1
2
3
curl -X POST "https://api-housing.boaz-study.tech/api/logements/" \
  -H "Content-Type: application/json" \
  -d '{"titre":"Test Studio","adresse":"1 Rue Test, Paris","ville":"Paris","code_postal":"75001","loyer":800}'

Vérifier si existe :

1
curl "https://api-housing.boaz-study.tech/api/logements/check-existence?adresse=1%20Rue%20Test&ville=Paris"

Voir tous les logements :

1
curl "https://api-housing.boaz-study.tech/api/logements/"

🏡 Bonne chance avec vos ajouts de logements ! Cette API est prête à recevoir tous vos biens immobiliers. 🚀