Démarrage rapide
La racine API ci-dessous correspond à l’environnement qui sert cette page. Les réponses sont servies en JSON et les erreurs suivent le même format sur les routes publiques.
Le flux technique documenté est: rechercher une adresse avec GET /api/v1/autocomplete/address, lire un aperçu public avec GET /api/v1/address-overview, puis, seulement avec un droit API actif, activer l’adresse 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.
Les endpoints publics donnent accès à la découverte Free pour une consultation humaine et manuelle. Ils ne constituent ni un essai de production ni une autorisation d’automatiser le Free.
API_ROOT="https://1dex.fr/api/v1"
curl -sS --get "$API_ROOT/autocomplete/address" \
--data-urlencode "q=10 Rue des Cordeliers 13100 Aix-en-Provence" \
--data "limit=5"
curl -sS --get "$API_ROOT/address-overview" \
--data-urlencode "address=10 Rue des Cordeliers 13100 Aix-en-Provence" \
-H "Accept: application/json"
const apiRoot = "https://1dex.fr/api/v1";
const url = new URL(apiRoot + "/address-overview");
url.searchParams.set("address", "10 Rue des Cordeliers 13100 Aix-en-Provence");
const response = await fetch(url, {
headers: { Accept: "application/json" },
});
if (!response.ok) throw new Error("1dex HTTP " + response.status);
console.log(await response.json());
{
"version": "address-overview-v1",
"resolved": {
"address": "10 Rue des Cordeliers 13100 Aix-en-Provence",
"cityCode": "13001"
},
"cards": [],
"sourceOutcomes": [],
"degraded": {}
}
Authentification
Les lectures publiques sont possibles dans les limites Free. Lorsqu’un compte professionnel dispose d’un droit API actif, il peut envoyer une clé avec l’en-tête Authorization: Bearer <CLE_API_1DEX> ou X-1dex-api-key.
Les clés se créent et se révoquent depuis le compte. Une clé invalide renvoie HTTP 401. Une clé valide sans abonnement API actif renvoie HTTP 403 avec api_subscription_required; un compte non professionnel renvoie api_professional_required.
Les clés sont confidentielles, réservées au serveur du client et ne doivent être ni placées dans une URL ou un navigateur, ni partagées ou revendues. Les droits payants restent séparés des 10 adresses/jour et 50/mois du Free manuel.
Réponses d’authentification
| Situation | HTTP | Action |
|---|
| Lecture publique autorisée | 200 | Traiter la réponse JSON et ses états degraded. |
| Clé absente, révoquée ou invalide | 401 | Créer ou renouveler une clé côté serveur. |
| Profil non professionnel ou droit API inactif | 403 | Vérifier le profil et l’offre active dans le compte. |
| Limite applicable atteinte | 429 | Respecter retry_after_seconds lorsqu’il est fourni. |
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.
Parcours API recommandé
| Méthode | Endpoint | Usage |
|---|
| GET | /autocomplete/address | Trouver une adresse normalisée. |
| GET | /address-overview | Lire l’aperçu public structuré. |
| POST | /address-unlocks | Activer une adresse avec un droit API actif. |
| GET | /address-details | Lire les familles détaillées demandées. |
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 professionnel pour récupérer les données d’une adresse activée en JSON avec une clé API et un droit actif. La réponse est versionnée address-details-v1.
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.
Les modalités commerciales d’activation et de relecture ne deviennent opposables qu’avec l’offre expressément présentée et acceptée au checkout. Tant que la V2 n’est pas ouverte, la présence de cette documentation ne permet pas d’acheter ni d’utiliser un abonnement V2.
SDK et exemples
Le dépôt public du connecteur regroupe du code source et des exemples CLI, JavaScript et curl. Le paquet @1dex/connector n’est pas publié sur npm à ce stade.
Utilisez ces exemples comme référence de développement locale. Ils ne créent aucun droit d’automatiser le Free ni d’utiliser les endpoints détaillés sans activation API.
Quotas et limites
Aucun prix ni quota commercial V2 n’est publié comme disponible tant que le produit et son Price Stripe ne sont pas activés. Le récapitulatif de commande fera foi pour le prix, la période, les droits et les limites acceptés.
Les limites techniques et les réponses HTTP 429 restent documentées séparément afin de permettre l’intégration et de protéger le service.
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.
