Démarrage rapide
Base URL de production: https://1dex.fr/api/v1. Les réponses sont servies en JSON et les erreurs suivent le même format sur les routes publiques.
Le flux recommandé pour intégrer une adresse est: rechercher une adresse avec GET /api/v1/autocomplete/address, lire un aperçu public avec GET /api/v1/address-overview, puis déverrouiller l’adresse avec POST /api/v1/address-unlocks avant d’appeler GET /api/v1/address-details.
GET /api/v1/public-preview sert à prévisualiser une URL publique déjà connue (/ville/..., /adresse/...). Pour une recherche client, utilisez autocomplete/address puis address-overview; public-preview n’est pas le point d’entrée recherche.
Authentification
Les appels anonymes sont possibles dans les quotas publics. Les usages abonnés peuvent envoyer une clé API avec l’en-tête Authorization: Bearer <CLE_API_1DEX> ou X-1dex-api-key.
Les clés API se créent depuis le compte 1dex. Une clé invalide renvoie HTTP 401. Une clé valide sans abonnement actif renvoie HTTP 403 avec api_subscription_required; un compte abonné non professionnel renvoie api_professional_required.
La clé API rattache l’usage au quota abonné API. Elle permet aussi d’appeler les endpoints abonnés: /api/v1/account/usage pour suivre points/crédits, /api/v1/address-unlocks pour consommer un crédit adresse, puis /api/v1/address-details pour lire les données achetées. Pendant le lancement, ces endpoints abonnés sont réservés aux comptes professionnels avec abonnement actif.
Référence API
La référence interactive est générée depuis le contrat OpenAPI réellement servi par le runtime. Elle permet de parcourir les endpoints et de tester les requêtes depuis une page Swagger aux couleurs 1dex.
Le fichier OpenAPI reste la source machine pour les générateurs de clients, catalogues externes et tests d’intégration.
Ce que renvoie address-overview
GET /api/v1/address-overview est l’endpoint conseillé pour un client qui veut exploiter une adresse en JSON sans reproduire l’interface Explorer.
La réponse est un contrat stable address-overview-v1: query, adresse résolue, ville, coordonnées, parcelle, cartes ordonnées et sourceOutcomes. Les cartes exposent des valeurs prêtes à intégrer plutôt que les tables internes brutes.
- Entrées acceptées: address, city_code, lon/lat ou parcel_record_key; des filtres DVF publics comme dvf_radius_m et dvf_year peuvent être ajoutés.
- Rayon DVF API public: 600 m ou 1 km. Le 4 km et certains filtres avancés restent réservés aux accès étendus de l’Explorer.
- Les états partiels sont explicites via degraded et sourceOutcomes pour éviter de masquer une source indisponible.
Détails complets abonnés
GET /api/v1/address-details est l’endpoint abonné pour récupérer les données d’une adresse déverrouillée en JSON avec une clé API active. La réponse est versionnée address-details-v1. Coût: address-details: 24 points.
Il ne renvoie pas tout par défaut: le client doit demander les familles voulues avec fields=summary,rail,mobile,tabs,map_layers,parcel_dvf,sources,source_outcomes ou fields=all.
Si l’adresse n’est pas encore déverrouillée, l’API répond address_unlock_required sans consommer les points address-details. Un achat par API se fait par POST /api/v1/address-unlocks avec address et city_code optionnel, lon/lat ou parcel_record_key; city_code seul ne suffit pas et contraint la commune résolue. Cet appel déduit un crédit si l’adresse n’est pas déjà active. Coût: address-unlock: 12 points après résolution valide.
SDK et exemples
Le connecteur officiel regroupe les exemples CLI, npm, SDK et curl pour intégrer les lectures ouvertes sans recopier le contrat HTTP à la main.
Utilisez-le pour prototyper une intégration, tester une adresse ou récupérer les réponses JSON/GeoJSON exposées sur 1dex.fr.
Quotas et limites
Les quotas distinguent les appels anonymes, connectés, abonnés et les clés API abonnées. Les coûts varient selon la famille d’endpoint.
La page quotas détaille les budgets, les coûts par route et le comportement HTTP 429 en cas de dépassement.
Données disponibles
Les réponses publiques sont centrées sur l’adresse: parcelles, aperçu DVF, loyers, risques, éducation, qualité de l’air, FDep, eau potable et contexte cartographique lorsque ces signaux sont disponibles.
L’API ne publie pas les bases brutes, les schémas internes, les procédures opérateur ni les champs instables ou sensibles.
