Le modèle de données
de l'API CFNEWS IMMO

01 À propos de doc.json

Le fichier https://api.cfnewsimmo.net/doc.json est la spécification OpenAPI 3.0 de l'API REST CFNEWS IMMO. C'est à la fois un modèle de données et un contrat d'interface machine-readable.

Elle décrit, dans un format standard exploitable par vos outils :

• les entités métier exposées — opérations, actifs immobiliers, acteurs, sociétés, véhicules, actualités, personnalités, mouvements ;
• chaque endpoint avec sa méthode HTTP, son chemin, ses paramètres typés (avec enum, formats, contraintes) ;
• les schémas de réponse (succès et erreurs) ;
• les règles d'authentification et la structure du quota.

02 Cartographie des entités

L'API CFNEWS IMMO organise son périmètre autour de huit entités principales. L'opération (transaction immobilière ou deal corporate) constitue l'objet pivot du modèle, avec une entité propre à l'univers immobilier : l'actif immobilier.

Modèle conceptuel simplifié des entités exposées par l'API CFNEWS IMMO.

Dictionnaire des entités

03 Authentification & quota

L'API utilise une authentification Bearer Token. Chaque appel doit présenter un token valide via l'en-tête Authorization.

Format de l'en-tête

Authorization: Bearer VOTRE_TOKEN
Accept: application/json

Endpoint quota

Structure de l'objet quota

Chaque réponse de l'API inclut un objet quota permettant de suivre votre consommation en temps réel :

04 Pagination & tri

Les endpoints de liste retournent leurs résultats sous forme paginée, avec métadonnées de navigation et le total de résultats correspondant aux filtres.

Paramètres communs

Métadonnées de pagination dans la réponse

05 Filtrage & référentiels

L'API CFNEWS IMMO propose un système de filtrage typé et contractuel : chaque filtre est documenté dans le doc.json avec son type, ses valeurs autorisées (enum) et ses contraintes.

Filtres typés (recommandé)

Les endpoints de recherche exposent des paramètres explicites, fortement typés, qui permettent une intégration robuste. Exemples pour /v1/operation :

La liste ci-dessus est un extrait. /v1/operation expose à elle seule plus de 40 paramètres typés. La spécification doc.json reste la source exhaustive.

Endpoint field-values — référentiels dynamiques

Pour chaque entité, un endpoint dédié permet de récupérer dynamiquement les valeurs autorisées d'un champ filtrable. Utile pour alimenter des dropdowns ou valider une saisie côté client.

Chaque endpoint field-values accepte un paramètre field[] indiquant les champs dont vous souhaitez la liste des valeurs.

06 Catalogue des endpoints

L'API expose une trentaine d'endpoints organisés par tag fonctionnel. Tableau synthétique ci-dessous, spécification complète dans doc.json.

Référentiels (recherche & détail)

Actualité

Portfolios & deal lists

Field-values (référentiels dynamiques)

Compte

07 Schémas de réponse

Les endpoints de liste partagent une enveloppe de réponse standard, qui combine données paginées, métadonnées et information de quota.

Enveloppe paginée

{
  "count":    5,           // résultats sur la page courante
  "total":    30,          // total correspondant aux filtres
  "page":     2,           // page courante
  "nb_pages": 2,           // nombre total de pages
  "quota": {
    "request_cost":  2,
    "monthly_used":  52,
    "monthly_limit": 2000
  },
  "items": [ /* tableau d'objets (Operation, ActifImmo, ArticlePreview, …) */ ]
}

Endpoint détail

Les endpoints /v1/{entité}/{id} retournent directement l'objet complet (sans enveloppe paginée). Le schéma de chaque entité est défini dans la section definitions du doc.json : Operation, ActifImmo, Vehicule, Societe, People, Mouvement, Article, Erreur…

Chaque objet embarque un bloc metadata commun : identifiant de contenu (id, main_node_id), published / modified (format Y-m-d), url de la fiche sur cfnewsimmo.net, endpoint d'API pour recharger l'objet, et son contenttype.

Champs remarquables du schéma Operation

Schéma d'erreur

Toutes les erreurs (4xx, 5xx) utilisent un schéma unifié Erreur (error : message, code : slug applicatif) permettant un traitement programmatique cohérent.

08 Codes d'erreur

L'API retourne des codes HTTP standards accompagnés d'un code applicatif identifiant la cause précise de l'erreur.

09 Paramètres de recherche par type de fiche

C'est le cœur de l'API. Chaque endpoint de recherche accepte un ensemble riche de paramètres typés — appelés queries dans la suite — qui correspondent exactement aux filtres disponibles dans l'interface cfnewsimmo.net. Construire des queries précises est le levier principal pour obtenir des résultats pertinents en limitant la consommation de quota.

Tableau de synthèse — combien de filtres par endpoint ?

9.1 — /v1/operation · Recherche d'opérations

L'endpoint le plus riche. Permet d'interroger la base de transactions CFNEWS IMMO sur tous les axes : nature du deal, actif, stratégie, géographie (jusqu'au rayon GPS), acquéreur / cédant, conseils, valorisation, rendement, dates, mots-clés.

Identification & descriptif de la cible

Nature de l'opération & stratégie

Caractéristiques de l'actif (surface, périmètre, loyer, rendement)

Recherche géographique par rayon (Deal Range GPS)

Acteurs (acquéreur / cédant / conseils)

Valorisation, montant, CA, dates, mots-clés

9.2 — /v1/actif_immobilier · Recherche d'actifs

Entité propre à CFNEWS IMMO : l'annuaire des immeubles et portefeuilles d'actifs, avec leur historique de transactions.

9.3 — /v1/acteur · Recherche d'acteurs

Annuaire des investisseurs, avocats / notaires et conseils financiers. Plusieurs filtres sont conditionnés au type d'acteur (paramètre acteur_domaine).

9.4 — /v1/societe · Recherche de sociétés

9.5 — /v1/vehicule · Recherche de véhicules

9.6 — /v1/mouvement · Mouvements & nominations

9.7 — /v1/people · Bottin des personnalités

9.8 — /v1/actualite · Articles

Récupérer les listes de valeurs dynamiquement

Pour chaque type de fiche, un endpoint field-values permet de récupérer dynamiquement la liste des valeurs autorisées pour un champ donné. Idéal pour alimenter un formulaire ou un dropdown sans coder en dur les IDs — indispensable pour les champs dépendants (asset_subtype, acteur_sous_domaine, people_sous_domaine) :

10 Exemples par endpoint

10.1 — Cas d'usage par endpoint

Les exemples ci-dessous illustrent des questions métier réelles avec leur traduction en requête HTTP. Pour chaque cas, le pattern Python requests équivalent suit directement.

A. /v1/operation — Recherche de transactions

(1) « Acquisitions de bureaux Paris QCA > 100 M€ en 2026 »

# curl
curl "https://api.cfnewsimmo.net/v1/operation?op_type[]=375872&asset_type[]=375173&perimeter[]=436226&Montantmin=100&depuis=01/01/2026&jusquau=31/12/2026" \
  -H "Authorization: Bearer $TOKEN"

# Python
params = {
    "op_type[]":    [375872],        # Transaction
    "asset_type[]": [375173],        # Bureaux
    "perimeter[]":  [436226],        # Paris QCA
    "Montantmin":   100,
    "depuis":  "01/01/2026",
    "jusquau": "31/12/2026",
}
r = requests.get(f"{API_BASE}/operation", headers=headers, params=params).json()

(2) « Toutes les transactions dans un rayon de 500 m autour d'un point GPS (Deal Range) »

params = {
    "latitude":  48.8721,            # ex. quartier Monceau, Paris 8e
    "longitude": 2.3095,
    "radius":    500,                # mètres — plage 250 à 10 000, pas de 250
}

(3) « VEFA en blanc sur la logistique, 2025–2026 »

params = {
    "op_strategy[]": [436399],        # vefa en blanc
    "asset_type[]":  [375061],        # Logistique / Industriel
    "depuis":  "01/01/2025",
    "jusquau": "31/12/2026",
}

(4) « Transactions hôtelières avec un taux de rendement entre 4 et 6 % »

params = {
    "asset_type[]":          [375169],  # Hôtellerie
    "op_ratemin":            4,
    "op_ratemax":            6,
    "uniqut_avec_rendement": "oui",     # exclut les opés sans taux
}

(5) « Sale & leaseback commerce, acquéreurs étrangers »

params = {
    "op_strategy[]":                  [436401],      # sale & leaseback
    "asset_type[]":                   [375166],      # Commerce
    "op_buyer":                       "oui",         # filtrage côté acquéreurs
    "op_nationality_solder_buyer[]":  ["etranger"],  # tout sauf France
}

(6) « Opérations data center & énergie 2026 (mots-clés AND, max 4) »

params = {
    "op_keywords[]":    [375290, 375364],   # data center, énergie
    "keyword_operator": "AND",
    "depuis":           "01/01/2026",
}

B. /v1/actif_immobilier — Annuaire des actifs

(1) « Bureaux > 10 000 m², neufs ou restructurés, valorisés > 150 M€ »

params = {
    "asset_type[]":           [375173],                      # Bureaux
    "asset_surface_range[]":  ["10000 et plus"],
    "asset_premises_state[]": [428044, 428047],              # Neuf, Restructuré
    "VALtranche[]":           ["150-250", "250-500", "500-1000", ">1000"],
}

(2) « Actifs de santé en Île-de-France »

params = {
    "asset_type[]":   [375136],       # Santé
    "asset_region[]": [375252],       # Île-de-France
}

C. /v1/acteur — Annuaire des acteurs

(1) « Foncières cotées françaises, AUM > 1 000 M€ »

params = {
    "acteur_domaine[]":  [428039],     # Investisseurs
    "investment_type[]": [454882],     # Foncière cotée
    "acteur_zone[]":     ["FR"],
    "aum_min":           1000,
}

(2) « Investisseurs ciblant la logistique, tickets 50–150 M€ »

params = {
    "acteur_domaine[]": [428039],      # Investisseurs
    "asset_type":       375061,        # Logistique / Industriel (valeur unique)
    "tranche_invest[]": [375974],      # 50-150
}

(3) « Études notariales et cabinets d'avocats à Paris, bureaux régionaux inclus »

params = {
    "acteur_domaine[]":         [428040],   # Avocats / Notaires
    "acteur_dpt[]":             ["75"],
    "include_regional_offices": 1,
}

D. /v1/vehicule — Véhicules d'investissement

(1) « Fonds immobiliers Article 8 en cours de levée > 250 M€ »

params = {
    "vehicle_segment[]": [375553],     # Immobilier
    "sfdr[]":            [443608],     # Article 8
    "vehicle_status[]":  [375560],     # En cours de levée
    "Montantmin":        250,
}

(2) « Fonds de dette immobilière, co-investissement possible »

params = {
    "vehicle_segment[]":     [375556],  # Dette
    "asset_type[]":          [375023],  # Dette immobilière
    "vehicle_type_invest[]": [375564],  # Co-investissement
}

E. /v1/acteur/portfolio_now/{id} — Portefeuille actuel

(1) « Portefeuille actuel complet d'un acteur, toutes pages »

all_ops = []
page = 1
while True:
    r = requests.get(f"{API_BASE}/acteur/portfolio_now/{ACTEUR_ID}",
                     headers=headers, params={"page": page}).json()
    all_ops.extend(r["items"])
    if page >= r["nb_pages"]: break
    page += 1
# 25 items/page — boucler jusqu'à nb_pages

(2) « Compter les sorties sans consommer de quota »

r = requests.get(f"{API_BASE}/acteur/portfolio_sortie/{ACTEUR_ID}",
                 headers=headers, params={"ping": "true"}).json()
print("Sorties :", r["total"])

10.2 — Exemples génériques

Exemples — curl

Rechercher les transactions de bureaux core en 2026

# Utiliser les filtres typés issus de la spécification
curl -X GET \
  "https://api.cfnewsimmo.net/v1/operation?asset_type[]=375173&op_strategy[]=375039&depuis=01/01/2026&jusquau=31/12/2026" \
  -H "Authorization: Bearer VOTRE_TOKEN" \
  -H "Accept: application/json"

Estimer le volume sans consommer de quota

# Ajouter ping=true
curl -X GET \
  "https://api.cfnewsimmo.net/v1/operation?asset_type[]=375169&ping=true" \
  -H "Authorization: Bearer VOTRE_TOKEN"

# Réponse :
{ "total": 842, "quota": { "request_cost": 0, ... } }

Exemples — Python (requests)

Recherche de transactions avec filtres typés

import requests

API_BASE = "https://api.cfnewsimmo.net/v1"
TOKEN    = "VOTRE_TOKEN"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Accept": "application/json",
}

# IMPORTANT : pour les filtres typés [], passer une liste à `params`.
# requests sérialise automatiquement en asset_type[]=375173&asset_type[]=375166
params = {
    "asset_type[]":  [375173, 375166],   # Bureaux + Commerce
    "op_strategy[]": [375041],           # value-add
    "region[]":      [375252],           # Île-de-France
    "depuis":        "01/01/2026",      # format d/m/Y
    "jusquau":       "31/12/2026",
    "page":          1,
}

resp = requests.get(f"{API_BASE}/operation", headers=headers, params=params)
resp.raise_for_status()
data = resp.json()

print(f"Total transactions : {data['total']}")
print(f"Quota utilisé ce mois : {data['quota']['monthly_used']} / {data['quota']['monthly_limit']}")

for deal in data["items"]:
    meta = deal.get("metadata", {})
    print(meta.get("id"), "-", meta.get("name"))

Compter sans consommer (ping=true)

def count_deals(asset_type_ids, year):
    """Retourne le nombre total de transactions correspondantes — coût quota : 0"""
    params = {
        "asset_type[]": asset_type_ids,
        "depuis":       f"01/01/{year}",
        "jusquau":      f"31/12/{year}",
        "ping":         "true",
    }
    r = requests.get(f"{API_BASE}/operation", headers=headers, params=params)
    r.raise_for_status()
    return r.json()["total"]

# Estimation rapide pour dimensionner une recherche
nb_bureaux = count_deals([375173], 2026)
nb_logist  = count_deals([375061], 2026)
print(f"Bureaux 2026 : {nb_bureaux} | Logistique 2026 : {nb_logist}")

Récupérer les valeurs autorisées d'un champ (field-values)

# Récupérer dynamiquement les sous-types d'actif Bureaux
# (idéal pour alimenter un dropdown côté front)
r = requests.get(
    f"{API_BASE}/operation/field-values",
    headers=headers,
    params={"field[]": ["asset_subtype"], "asset_type[]": [375173]},
)
r.raise_for_status()
print(r.json())

Gestion des erreurs (429, 422, 403)

import time

def safe_get(url, params=None, max_retries=3):
    """GET avec backoff exponentiel sur 429 et gestion des erreurs métier."""
    for attempt in range(max_retries):
        r = requests.get(url, headers=headers, params=params)

        if r.status_code == 200:
            return r.json()

        if r.status_code == 429:                # too_many_requests
            wait = 2 ** attempt
            print(f"Rate limit, attente {wait}s...")
            time.sleep(wait)
            continue

        if r.status_code == 422:                # too_broad_search
            raise ValueError("Recherche trop large, ajoutez des filtres")

        if r.status_code == 403:                # forbidden / limit_exceeded
            err = r.json()
            raise PermissionError(err.get("error", "Accès refusé"))

        r.raise_for_status()

    raise RuntimeError("Échec après plusieurs tentatives")

Exemples — JavaScript / TypeScript

Récupération paginée avec fetch

async function getFullPortfolio(acteurId, token) {
  const all = [];
  let page = 1;
  while (true) {
    const res = await fetch(
      `https://api.cfnewsimmo.net/v1/acteur/portfolio_now/${acteurId}?page=${page}`,
      { headers: { Authorization: `Bearer ${token}` } }
    );
    const data = await res.json();
    all.push(...data.items);
    if (page >= data.nb_pages) break;
    page++;
  }
  return all;
}

Génération d'un SDK typé depuis la spécification

# 1. Récupération de la spec
curl -o cfnewsimmo-swagger.json https://api.cfnewsimmo.net/doc.json

# 2. Génération d'un client TypeScript
npx @openapitools/openapi-generator-cli generate \
  -i cfnewsimmo-swagger.json \
  -g typescript-axios \
  -o ./cfnewsimmo-sdk

# Le SDK généré gère automatiquement :
# - les types stricts (op_type, asset_type, op_strategy…)
# - l'authentification Bearer
# - la sérialisation des tableaux (asset_type[]=375173&asset_type[]=375166)

11 Que faire de doc.json ?

La spécification CFNEWS IMMO est conçue pour être opérationnelle : elle alimente directement vos outils de développement, de documentation et d'intégration.