Documentation Casapulse Data Hub

API

Format des requêtes

À noter : le nom de domaine n’est pas indiqué par la suite dans les exemples de requêtes

  • L’authentification est réalisée avec un paramètre de requête api_key spécifié dans chaque requête.

  • La requête complète se compose du domaine, suivi d'une URI, puis des paramètres de requêtes et du paramètre api_key
    Exemple : https://api.casapulse.fr/uri/?parametre=valeur&api_key=xxxxxxxxxxxxx

À noter : le paramètre api_key n’est pas indiqué par la suite dans les exemples de requêtes

  • Tous les paramètres de requête sont optionnels avec une valeur par défaut, sauf api_key.

  • Les réponses sont renvoyées au format JSON, non indenté par défaut, et indenté si le paramètre de requête indent est spécifié.

  • En cas d’erreur, le code HTTP de la réponse est supérieur ou égal à 400. Un code 400 signifie qu’un ou plusieurs paramètres sont invalides. Dans ce cas, le détail de l’erreur est donné dans le corps de la réponse.

À noter :

  • Les URIs (partie précédant les paramètres de requêtes) doivent se terminer avec un slash

  • Les valeurs des paramètres de requêtes doivent être URL-encodées

  • Chaque service ci-dessous est accompagné d'exemples en ligne utilisant une clé API de test

Services disponibles


Recherche de localisations

Permet de rechercher des communes, départements, régions, ou code postaux à partir d’une chaîne de caractères et d’obtenir les IDs et autres informations (nom, code postal...) des lieux correspondants.

Ces IDs ou informations peuvent être passés comme valeurs dans les paramètres city, department, region du service Recherche d’annonces, et du service Données de marché (voir ci-dessous).

Remarque : cette requête renvoie 20 résultats au maximum.

URI

/locations/search/

Méthode

GET

Paramètres

  • query (string, défaut null) Chaîne de caractères à rechercher, qui peut être un nom ou partie de nom de ville, département, ou région, un code postal, numéro de département, etc., ou bien une combinaison de ces éléments.

Format de la réponse

				{
				  /* La chaîne donnée en entrée. */
				  "query": "velizy",
				  /* Liste des résultats. */
				  "results": [
				    {
				      /* ID de la localisation. */
				      "id": "43ba90b1-8b19-4011-9ed4-41b7e1716cdb",
				      /* Code Insee de la localisation. */
				      "insee_code": "78640",
				      /* Code postal si le type de localisation est "city", sinon null. */
				      "zip_code": "78140",
				      /* Nom de la localisation. */
				      "name": "Vélizy-Villacoublay",
				      /* Nom de la localisation en minuscules sans caractères spéciaux. */
				      "slug": "velizy villacoublay",
				      /* Type de localisation, peut être "city", "department", ou "region". */
				      "location_type": "city"
				    }
				  ]
				}

Exemples en ligne


Liste des types de biens et sources

Renvoie la liste des IDs et dénominations des types de biens (appartement, maison…) et des sources (plateformes de publication d'annonces) disponibles, pouvant être utilisés comme valeurs dans les paramètres property_type et source du service Recherches d’annonces (voir ci-dessous).

URI

/properties/listings/options/

Méthode

GET

Paramètres

Aucun

Format de la réponse

				{
				  /* Liste des sources disponibles (plateformes de publication d'annonces),
				  tronqué à 1 dans cet exemple */
				  "sources": [
				    {
				      /* ID de la source */
				      "id": "e771f32f-af39-4ef3-aef8-3e1793848f32",
				      /* Code de la source */
				      "code": "PARU_VENDU",
				      /* Nom de la source */
				      "name": "ParuVendu"
				    }
				  ],
				  /* Liste des types de biens disponibles, tronqué à 1 dans cet exemple */
				  "property_types": [
				    {
				      /* ID du type de bien */
				      "id": "6f2af4e2-77e4-4430-a4d8-e8899ca91c0a",
				      /* Code du type de bien */
				      "value": "APARTMENT"
				    }
				  ]
				}


Recherche d’annonces

Liste les annonces immobilières disponibles sur Casapulse, avec la possibilité de filtrer et trier sur plusieurs critères passés en paramètres de la requête.

URI

/properties/listings/

Méthode

GET

Paramètres

  • city (UUID ou string, défaut null) Commune, arrondissement, ou code postal spécifique.

    • Les valeurs possibles sont un nom, un code postal, ou bien l'ID ou la valeur des champs name, slug, zip_code, ou insee_code des résultats renvoyés par le service Recherche de localisations.

    • Il est possible de passer plusieurs fois le paramètre city dans une requête pour filtrer sur plusieurs villes.

  • department (UUID ou string, défaut null) Département.

    • Les valeurs possibles sont un nom, un code de département, ou bien l'ID ou la valeur des champs name, slug, ou insee_code des résultats renvoyés par le service Recherche de localisations.

    • Il est possible de passer plusieurs fois le paramètre department dans une requête pour filtrer sur plusieurs départements.

  • region (UUID ou string, défaut null) Région.

    • Les valeurs possibles sont un nom, un code de région, ou bien l'ID ou la valeur des champs name, slug, ou insee_code des résultats renvoyés par le service Recherche de localisations.

    • Il est possible de passer plusieurs fois le paramètre region dans une requête pour filtrer sur plusieurs régions.

  • radius (int, défaut null) Rayon de recherche en km autour des communes spécifiées dans les paramètres city (ne s'applique pas aux paramètres department et region).

  • property_type (UUID ou string, défaut null) Type de bien (appartement, maison…).

    • Les valeurs possibles sont l'ID, ou la valeur du champ value des résultats renvoyés par le service Liste des types de biens et sources.

    • Il est possible de passer plusieurs fois le paramètre property_type dans une requête pour filtrer sur plusieurs types de biens.

  • source (UUID ou string, défaut null) Plateforme de publication d'annonces.

    • Les valeurs possibles sont l'ID, ou la valeur des champs code ou name des résultats renvoyés par le service Liste des types de biens et sources.

    • Il est possible de passer plusieurs fois le paramètre source dans une requête pour filtrer sur plusieurs sources.

  • keywords (string, défaut null) Mots-clés présents dans la description des annonces.

    • Insensible à la casse, l'accentuation, et d'autres variations comme les pluriels et traits d'union.

    • La requête renvoie les annonces contenant l'ensemble des mots-clés spécifiés, séparés par un espace.

    • Pour considérer plusieurs mots comme un mot-clé unique, entourez-les avec des guillemets, ex : "grande piscine".

    • Pour inclure les annonces contenant un ou plusieurs mots-clés, séparez-les avec le mot OU en majuscules, ex :  loué OU occupé.

    • Pour exclure les annonces contenant certains mots-clés, précédez-les d'un tiret, ex : -"dernier étage".

    • Vous pouvez combiner des mots-clés et des conditions de recherche en utilisant des parenthèses, ex :  (proximité OU proche) (metro OU gare).

  • duplicates (boolean, défaut false) Indique si la requête doit renvoyer les annonces correspondant à des biens identiques publiés sur différentes plateformes. Si false, renvoie la première annonce postée pour un bien donné.

  • individuals_only (boolean, défaut false) Annonces de particuliers uniquement.

  • rooms_min (int, défaut null) Nombre de pièces minimum.

  • rooms_max (int, défaut null) Nombre de pièces maximum.

  • surface_min (int, défaut null) Surface minimum.

  • surface_max (int, défaut null) Surface maximum.

  • price_min (int, défaut null) Prix minimum.

  • price_max (int, défaut null) Prix maximum.

  • rental_yield_estimate_min (decimal, défaut null) Rendement locatif brut estimé minimum (pourcentage).

  • rental_yield_estimate_max (decimal, défaut null) Rendement locatif brut estimé maximum (pourcentage).

  • price_m2_min (int, défaut null) Prix au m² minimum.

  • price_m2_max (int, défaut null) Prix au m² maximum.

  • floor_min (int, défaut null) Étage minimum.

  • floor_max (int, défaut null) Étage maximum.

  • parking (boolean, défaut null) Présence d’un parking.

  • basement (boolean, défaut null) Présence d’une cave.

  • elevator (boolean, défaut null) Présence d’un ascenseur.

  • balcony (boolean, défaut null) Présence d’un balcon.

  • terrace (boolean, défaut null) Présence d’une terrasse.

  • population_min (int, défaut null) Nombre d'habitants minimum dans la commune du bien.

  • population_max (int, défaut null) Nombre d'habitants maximum dans la commune du bien.

  • population_variation_5y_min (decimal, défaut null) Variation minimum de population dans la commune du bien sur 5 ans (pourcentage positif ou négatif).

  • population_variation_5y_max (decimal, défaut null) Variation maximum de population dans la commune du bien sur 5 ans (pourcentage positif ou négatif).

  • population_density_min (int, défaut null) Densité de population minimum dans la commune du bien (habitants/km²).

  • population_density_max (int, défaut null) Densité de population maximum dans la commune du bien (habitants/km²).

  • housings_vacant_share_min (decimal, défaut null) Taux de logements vacants minimum dans la commune du bien.

  • housings_vacant_share_max (decimal, défaut null) Taux de logements vacants maximum dans la commune du bien.

  • unemployment_rate_min (decimal, défaut null) Taux de chômage minimum dans la commune du bien.

  • unemployment_rate_max (decimal, défaut null) Taux de chômage maximum dans la commune du bien.

  • median_income_min (int, défaut null) Revenu annuel médian minimum dans la commune du bien.

  • median_income_max (int, défaut null) Revenu annuel médian maximum dans la commune du bien.

  • from_date (date au format ISO 8601, défaut date actuelle moins 1 mois) Date minimum de création des annonces. La valeur minimum supportée est la date actuelle moins 6 mois.

  • to_date (date au format ISO 8601, défaut date actuelle) Date maximum de création des annonces.

  • page_size (int, défaut 25) Nombre de résultats à renvoyer par requête. La valeur maximum supportée est 100.

  • page (int, défaut 1) Numéro de page souhaité pour les requêtes comprenant plusieurs pages de résultats.

  • limit (int, défaut 1000) Nombre total de résultats maximum à renvoyer. Une valeur basse peut, selon les critères de recherche, réduire le temps d'exécution de la requête. La valeur maximum supportée est 1000.

  • ordering (string, défaut -created) Critère de tri des résultats.

    • Un signe “moins” devant la valeur indique un tri par ordre décroissant.

    • Les valeurs possibles sont : city, zip_code, property_type, rooms, surface, price, price_m2, created, -city, -zip_code, -property_type, -rooms, -surface, -price, -price_m2, -created

Format de la réponse

				{
				  /* Taille de la page actuelle. */
				  "page_size": 25,
				  /* Nombre de pages total de la requête. */
				  "total_pages_count": 400,
				  /* Numéro de la page actuelle. */
				  "current_page": 1,
				  /* Nombre total de résultats de la requête (limité à 1000). */
				  "total_items_count": 1000,
				  /* Indique si le nombre maximum de résultats est atteint. */
				  "limit_reached": true,
				  /* Numéro du premier résultat de la page sur le total de résultats. */
				  "current_items_start": 1,
				  /* Numéro du dernier résultat de la page sur le total de résultats. */
				  "current_items_end": 25,
				  /* Liste de résultats de la page actuelle, tronqué à 1 dans cet exemple. */
				  "items": [
				    {
				      /* ID de l’annonce. */
				      "id": "cbe1f718-bfb8-4544-aea6-2bee0cce4fc2",
				      /* Date d’ajout de l’annonce dans la base Casapulse. */
				      "created": "2021-06-08T02:32:16.165485Z",
				      /* Plateforme de publication de l’annonce (source). */
				      "source": {
				        /* ID de la source. */
				        "id": "e771f32f-af39-4ef3-aef8-3e1793848f32",
				        /* Code de la source. */
				        "code": "SE_LOGER",
				        /* Nom de la source. */
				        "name": "Se Loger"
				      },
				      /* URL vers l’annonce d’origine. */
				      "url": "https://www.seloger.com/annonces/174024877.htm",
				      /* URL des images de l’annonce, vide si pas d'image disponible. */
				      "img_url_1": "https://v.seloger.com/s/ea9q9in1d44ug913879j5y3bw0zk.jpg",
				      "img_url_2": "https://v.seloger.com/s/ea9q9in1d44ug913879j5y3bw0zk.jpg",
				      "img_url_3": "https://v.seloger.com/s/ea9q9in1d44ug913879j5y3bw0zk.jpg",
				      "img_url_4": "https://v.seloger.com/s/ea9q9in1d44ug913879j5y3bw0zk.jpg",
				      "img_url_5": "https://v.seloger.com/s/ea9q9in1d44ug913879j5y3bw0zk.jpg",
				      "img_url_6": "https://v.seloger.com/s/ea9q9in1d44ug913879j5y3bw0zk.jpg",
				      /* True si l'annonce n'est actuellement plus en ligne. */
				      "offline": false,
				      /* ID du bien listé dans l’annonce. */
				      "property": "1f78aa15-08b2-4096-887e-fe1088584e13",
				      /* True si une annonce pour le même bien a été publiée
				      sur une autre plateforme. */
				      "duplicate": false,
				      /* "Agency" si l’annonce est postée par une agence,
				      "Individual" si l’annonce est publiée par un particulier. */
				      "agency": "Agency",
				      /* Prix du bien en euros. */
				      "price": 600000,
				      /* Prix au m² du bien en euros. */
				      "price_m2": 1802,
				      /* Nombre d'annonces de location postées dans les 6 derniers
				      mois pour des biens similaires dans la même ville, null si l'information
				      n'est pas connue. */
				      "rental_count": 16,
				      /* Loyer au m² moyen observé pour des biens similaires dans la
				      même ville, null si l'information n'est pas connue. */
				      "average_rent_m2": 9,
				      /* Rendement locatif brut estimé du bien, null si l'information n'est
				      pas connue. */
				      "rental_yield_estimate": 6.4,
				      /* Description de l'annonce */
				      "description": "Maison de 333m2 habitables bien agencée située en...",
				      /* Type du bien. */
				      "property_type": {
				        /* ID du type de bien. */
				        "id": "2c0f1544-83c5-4112-adb5-7145d0b2ce57",
				        /* Code du type de bien. */
				        "value": "HOUSE"
				      },
				      /* Localisation du bien. */
				      "city": {
				        /* ID de la ville. */
				        "id": "aaa3d7b9-9af6-44cc-b9da-96e557609ee1",
				        /* Code Insee de la ville. */
				        "insee_code": "07217",
				        /* Code postal de la ville. */
				        "zip_code": "07300",
				        /* Nom de la ville. */
				        "name": "Saint-Barthélemy-le-Plain",
				        /* Nom de la ville en minuscules et sans caractères spéciaux. */
				        "slug": "saint barthelemy le plain",
				        /* Type de localisation (toujours "city" dans les
				        résultats de recherche). */
				        "location_type": "city"
				      },
				      /* Adresse du bien (vide, ou bien nom et code postal de
				      la ville quand l'adresse n'est pas connue). */
				      "address": "",
				      /* Surface en m² du bien. */
				      "surface": 333.0,
				      /* Surface carrez en m² du bien, null si l’information n’est
				      pas connue. */
				      "surface_carrez": 333.0,
				      /* Nombre de pièces. */
				      "rooms": 8,
				      /* Indique l’étage, null si l’information n’est pas connue. */
				      "floor": 3,
				      /* Indique si le bien possède un parking. false pour non,
				      true pour oui, null si l’information n’est pas connue. */
				      "parking": true,
				      /* Indique si le bien possède une cave. false pour non,
				      true pour oui, null si l’information n’est pas connue. */
				      "basement": true,
				     /* Indique si l’immeuble du bien possède un ascenseur. false
				     pour non, true pour oui, null si l’information n’est pas connue. */
				      "elevator": true,
				      /* Indique si le bien possède un balcon. false pour non,
				      true pour oui, null si l’information n’est pas connue. */
				      "balcony": true,
				      /* Indique si le bien possède une terrasse. false pour non,
				      true pour oui, null si l’information n’est pas connue. */
				      "terrace": true
				    }
				  ]
				}

Exemples en ligne


Données de marché

Permet d'obtenir les informations de volumes, prix, variations de prix, et rendements locatifs pour les localisations et types de biens spécifiés.

Les données renvoyées correspondent aux moyennes pondérées sur l'ensemble des localisations, types de biens, et nombre de pièces minimum et maximum spécifiés dans les paramètres de la requête.

Les informations fournies sont calculées sur la base des dernières transactions réelles issues des bases de données notariales, et des données issues des offres publiées sur les plateformes d'annonces immobilières couvertes par Casapulse.

URI

/locations/market/

Méthode

GET

Paramètres

  • city (UUID ou string, défaut null) Commune, arrondissement, ou code postal spécifique.

    • Les valeurs possibles sont un nom, un code postal, ou bien l'ID ou la valeur des champs name, slug, zip_code, ou insee_code des résultats renvoyés par le service Recherche de localisations.

    • Il est possible de passer plusieurs fois le paramètre city dans une requête pour filtrer sur plusieurs villes.

  • department (UUID ou string, défaut null) Département.

    • Les valeurs possibles sont un nom, un code de département, ou bien l'ID ou la valeur des champs name, slug, ou insee_code des résultats renvoyés par le service Recherche de localisations.

    • Il est possible de passer plusieurs fois le paramètre department dans une requête pour filtrer sur plusieurs départements.

  • region (UUID ou string, défaut null) Région.

    • Les valeurs possibles sont un nom, un code de région, ou bien l'ID ou la valeur des champs name, slug, ou insee_code des résultats renvoyés par le service Recherche de localisations.

    • Il est possible de passer plusieurs fois le paramètre region dans une requête pour filtrer sur plusieurs régions.

  • radius (int, défaut null) Rayon de recherche en km autour des communes spécifiées dans les paramètres city (ne s'applique pas aux paramètres department et region).

  • property_type (UUID ou string, défaut null) Type de bien (appartement, maison…).

    • Les valeurs possibles sont l'ID, ou la valeur du champ value des résultats renvoyés par le service Liste des types de biens et sources.

    • Pour ce service, seuls les types de biens dont le champ value est APARTMENT ou HOUSE sont supportés.

    • Il est possible de passer plusieurs fois le paramètre property_type dans une requête pour filtrer sur plusieurs types de biens.

  • rooms_min (int, défaut null) Nombre de pièces minimum.

  • rooms_max (int, défaut null) Nombre de pièces maximum.

Format de la réponse

				{
				    /* Nombre de villes correspondant aux paramètres city, department,
				    region. */
				    "city_matches": 463,
				    /* Objet localisation du même format que les résultats
				    renvoyés par le service Recherche de localisations.
				    Spécifié si une unique localisation correspond aux paramètres
				    city, department, et region, sinon null. */
				    "exact_match": {
				        "id": "e4d7574c-4248-41e6-aed1-38bce2b1168d",
				        "insee_code": "17",
				        "zip_code": null,
				        "name": "Charente-Maritime",
				        "slug": "charente maritime",
				        "location_type": "department"
				    },
				    "data": {
				        /* Données basées sur les transactions historiques. */
				        "transaction_market": {
				            /* Nombre de transactions sur la dernière année. */
				            "count": 1137,
				            /* Prix au m² moyen sur la dernière année. */
				            "average_price_m2": 2812,
				            /* Variation de prix au m² sur la dernière année (pourcentage). */
				            "price_m2_variation_1y": 8.4,
				            /* Variation de prix au m² sur les 5 dernières années
				            (pourcentage). */
				            "price_m2_variation_5y": 15.6
				        },
				        /* Données basées sur les annonces immobilières. */
				        "listing_market": {
				            "sales": {
				                /* Nombre d'annonces de vente sur la dernière année. */
				                "count": 12226,
				                /* Prix au m² moyen des annonces de vente sur la dernière
				                année. */
				                "average_price_m2": 3716
				            },
				            "rental": {
				                /* Nombre d'annonces de location sur la dernière année. */
				                "count": 4596,
				                /* Prix au m² moyen des annonces de location sur la dernière
				                année. */
				                "average_price_m2": 14
				            }
				        },
				        /* Moyenne du rendement locatif brut estimé (loyer annuel observé
				        divisé par le prix de vente). */
				        "rental_yield_estimate": 4.8
				    }
				}

Exemples en ligne