Autocompletado en embudo - API estándar
Cree un formulario de dirección basado en el código postal con los endpoints clásicos CP/ADR/COMPL: busque la ciudad a partir de un código postal o un nombre, liste sus calles y, después, muestre las opciones de sub-edificio una vez seleccionada una calle.
Flujo de autocompletado en tres pasos
Formato de mayúsculas - El uso de mayúsculas
sigue la norma postal del país correspondiente.
Búsqueda de ciudad (CP)
Primer paso del enfoque en embudo. Devuelve las ciudades
y códigos postales coincidentes a partir de un código postal
parcial o un nombre de ciudad. El IDLocalite
de cada resultado alimenta el siguiente paso: ADR.
Solicitud
CP admite tanto GET como POST.
{SERVER_ADDRESS} y {LICENCE_CODE}
son proporcionados por DQE al crear la cuenta. Póngase en
contacto con su gestor de cuenta de DQE para obtener estas
credenciales.
GEThttps://{SERVER_ADDRESS}/CP/?CodePostal={POSTAL_CODE}&Alpha=True&Pays={COUNTRY_CODE}&Licence={LICENCE_CODE}
Ejemplo cURL
Francia - Búsqueda por código postal
curl "https://{SERVER_ADDRESS}/CP/?CodePostal=75008&Alpha=True&Pays=FRA&Licence={LICENCE_CODE}"
fetch("https://{SERVER_ADDRESS}/CP/?" + new
URLSearchParams({
CodePostal: "75008",
Alpha: "True",
Pays: "FRA",
Licence: "{LICENCE_CODE}"
}))
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.get(
"https://{SERVER_ADDRESS}/CP/",
params={
"CodePostal": "75008",
"Alpha": "True",
"Pays": "FRA",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$params = http_build_query([
'CodePostal' => '75008',
'Alpha' => 'True',
'Pays' => 'FRA',
'Licence' => '{LICENCE_CODE}',
]);
$ch = curl_init("https://{SERVER_ADDRESS}/CP/?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
axios.get('https://{SERVER_ADDRESS}/CP/',
{
params: {
CodePostal: '75008',
Alpha: 'True',
Pays: 'FRA',
Licence: '{LICENCE_CODE}'
}
})
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String url = "https://{SERVER_ADDRESS}/CP/"
+ "?CodePostal=75008&Alpha=True&Pays=FRA&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.GET()
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var url = "https://{SERVER_ADDRESS}/CP/"
+
"?CodePostal=75008&Alpha=True&Pays=FRA&Licence={LICENCE_CODE}";
var response = await client.GetAsync(url);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://{SERVER_ADDRESS}/CP/" +
"?CodePostal=75008&Alpha=True&Pays=FRA&Licence={LICENCE_CODE}"
resp, err := http.Get(url)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
POSThttps://{SERVER_ADDRESS}/CP/
Envíe todos los parámetros en el cuerpo de la solicitud
usando
Content-Type: application/x-www-form-urlencoded.
La dirección del servidor permanece en la URL.
Ejemplo cURL
curl -X POST "https://{SERVER_ADDRESS}/CP/"
\
-H "Content-Type: application/x-www-form-urlencoded"
\
-d "CodePostal=75008" \
-d "Alpha=True" \
-d "Pays=FRA" \
-d "Licence={LICENCE_CODE}"
fetch("https://{SERVER_ADDRESS}/CP/", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded"
},
body: new URLSearchParams({
CodePostal: "75008",
Alpha: "True",
Pays: "FRA",
Licence: "{LICENCE_CODE}"
})
})
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.post(
"https://{SERVER_ADDRESS}/CP/",
data={
"CodePostal": "75008",
"Alpha": "True",
"Pays": "FRA",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$ch = curl_init("https://{SERVER_ADDRESS}/CP/");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'CodePostal' => '75008',
'Alpha' => 'True',
'Pays' => 'FRA',
'Licence' => '{LICENCE_CODE}',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
const qs = require('querystring');
axios.post('https://{SERVER_ADDRESS}/CP/',
qs.stringify({
CodePostal: '75008',
Alpha: 'True',
Pays: 'FRA',
Licence: '{LICENCE_CODE}'
}))
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String form = "CodePostal=75008&Alpha=True&Pays=FRA&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{SERVER_ADDRESS}/CP/"))
.header("Content-Type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(form))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var form = new Dictionary<string, string>
{
["CodePostal"] = "75008",
["Alpha"] = "True",
["Pays"] = "FRA",
["Licence"] = "{LICENCE_CODE}"
};
var response = await client.PostAsync(
"https://{SERVER_ADDRESS}/CP/",
new FormUrlEncodedContent(form));
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
form := url.Values{}
form.Set("CodePostal", "75008")
form.Set("Alpha", "True")
form.Set("Pays", "FRA")
form.Set("Licence", "{LICENCE_CODE}")
resp, err := http.PostForm("https://{SERVER_ADDRESS}/CP/",
form)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
Parámetros
| Parameter | Valor | Descripción | Obl. / Opc. |
|---|---|---|---|
| Licence |
{LICENCE_CODE}
|
Su clave de licencia DQE o token OAuth2. Póngase en contacto con soporte si aún no dispone de una. | Obligatorio |
| CodePostal |
{POSTAL_CODE}
|
Código postal o nombre de ciudad introducido. | Obligatorio |
| Pays |
{COUNTRY_CODE}
|
Código de país ISO 3166-1 alfa-3 para el ámbito
de búsqueda de la dirección. Ejemplo: FRA
o GBR.
|
Obligatorio |
| Alpha |
True
|
Envíe siempre True. Parámetro obligatorio.
|
Obligatorio |
| Instance |
{INSTANCE}
|
No se devuelve en los resultados de este endpoint - se puede omitir sin problema. | Opcional |
| Etendue |
Y or N
|
Permite la búsqueda desde solo 2 caracteres en
el código postal introducido. Por defecto: N.
|
Opcional |
| NbMax |
{NB}
|
Número máximo de sugerencias de localidad devueltas. | Opcional |
| Filter |
{FILTER}
|
Controla el tipo de resultados devueltos. Si
se omite, la respuesta incluye códigos postales,
calles (si están disponibles) y entradas CEDEX.1 = código postal y CEDEX únicamente
· 2 = código postal y calle (sin
CEDEX) · 3 = solo código postal
· 4 = una sugerencia por código
postal y ciudad (solo Malasia)
|
Opcional |
| Langue |
{LANGUAGE}
|
Filtra los resultados por idioma/escritura. JPN:
JP = Kanji · JK =
Katakana · EN = Romanizado. HKG:
EN · ZH. THA: EN
· TH. Consulte la
guía de idiomas.
|
Opcional |
Francia y Bélgica: los códigos postales
pueden corresponder a varios municipios (agrupación fragmentada).
CP devolverá una fila de resultado por municipio.
Respuesta
Si la solicitud tiene éxito, la API devuelve un objeto JSON.
Las claves son números de clasificación de "1"
a "n", cada una asociada a un diccionario de
campos de dirección.
Esquema de respuesta variable - Cuando
IDVoie está presente, Voie aparece
en el JSON. Cuando solo se devuelve una ciudad, Voie
está ausente. Use un IDVoie no vacío para detectar
qué esquema se aplica.
Orden de los resultados - Los resultados
se clasifican por relevancia, no por código postal ascendente.
Cuando se introduce un código postal exacto que corresponde
a una sola ciudad, se devuelve un único resultado. Cuando
se introduce un código postal parcial con
Etendue=Y,
los resultados se ordenan por densidad de población (la ciudad
más grande primero). Cuando se introduce un nombre de ciudad
(exacto o parcial), las coincidencias exactas aparecen primero,
seguidas de una clasificación por relevancia de palabras
clave.
| Field | Descripción | Francia | Internacional |
|---|---|---|---|
| Province |
Código ISO del estado o región administrativa
(p. ej. 17 para Japón).
|
String (50) | String (50) |
| IDLocalite | Identificador único de la ciudad (código INSEE para Francia). | String (20) | String (20) |
| Pays | Código de país ISO 3166-1 alfa-3. | String (3) | String (3) |
| Instance | Campo interno. | String | String |
| CodePostal | Código postal de la dirección. | String (10) | String (10) |
| SousLocalite | Sublocalidad (distrito, barrio, suburbio). | Empty | String (50) |
| LieuDit | Localidad o aldea con nombre (Francia) o campo equivalente a nivel de distrito (internacional). La disponibilidad varía según el país. | String (38) | String (50) |
| Localite | Nombre de la ciudad. | String (38) | String (50) |
| Latitude | Geocoordenadas de la localidad encontrada. No disponible para todos los países - consulte la cobertura. | String | String |
| Longitude | Geocoordenadas de la localidad encontrada. No disponible para todos los países - consulte la cobertura. | String | String |
| IDVoie |
Identificador único de la calle. Solo se completa
cuando el código postal corresponde a una calle
específica. Si está presente, puede omitir ADR
y pasar IDVoie directamente a COMPL.
|
String (20) | String (20) |
| Voie |
Nombre de la calle. Solo presente en la respuesta
cuando IDVoie está completo.
|
String (38) | String (150) |
|
NbNumero also: Nbnumero |
Número total de números de calle en la calle
encontrada. Solo se completa cuando IDVoie
está presente; vacío en caso contrario. Ambas
claves (NbNumero / Nbnumero)
se refieren al mismo valor.
|
String | String |
| ListeNumero |
Lista de números de calle válidos separados por
punto y coma para la calle encontrada. Siempre
contiene todos los números cuando está presente;
vacía cuando IDVoie está ausente.
|
String (1024) | String (1024) |
| Numero | Número de calle completo, incluyendo cualquier complemento (bis, ter, etc.). | String (38) | String (38) |
| TypeVoie |
Tipo de vía (p. ej., RUE, AVENUE,
BOULEVARD). No se devuelve para
todos los conjuntos de datos internacionales.
|
String (20) | String (20) |
| Complement | Información adicional de la dirección. | Empty | String (50) |
| Entreprise | Nombre de la empresa asociada a la dirección. | String (38) | String (38) |
| Cedex |
Indicador CEDEX: 1 = dirección CEDEX,
0 = no CEDEX.
|
String (1) | String (1) |
| Region1 |
Etiqueta ISO del estado o región administrativa
(p. ej. ISHIKAWA para Japón).
|
Not available | String (50) |
| Region2 | Condado o nivel administrativo equivalente. | Not available | String (50) |
| Region3 | Condado o equivalente (nivel alternativo). | Not available | String (50) |
| Region4 | Información regional o administrativa adicional. | Not available | String (50) |
Ejemplo de respuesta
Ejemplo de respuesta - Francia (75008 París)
{
"1": {
"Province":
"*",
"IDLocalite":
"75108",
"NbNumero":
"",
"Pays":
"FRA",
"IDVoie":
"",
"Cedex":
"0",
"Numero":
"",
"TypeVoie":
"",
"Instance":
"",
"ListeNumero":
"",
"CodePostal":
"75008",
"SousLocalite":
"",
"LieuDit":
"",
"Latitude":
"48.8775112171854",
"Localite":
"PARIS",
"Longitude":
"2.31760169076841",
"Complement":
"",
"Entreprise":
""
}
}
Ejemplo de respuesta - Japón (108-6390)
{
"1": {
"Cedex":
"0",
"CodePostal":
"108-6390",
"Complement":
"",
"Entreprise":
"",
"IDLocalite":
"402574_1086390",
"IDVoie":
"",
"Instance":
"0",
"Latitude":
"",
"LieuDit":
"",
"ListeNumero":
"",
"Localite":
"ﾐﾅﾄｸ",
"Longitude":
"",
"NbNumero":
"",
"Numero":
"",
"Pays":
"JPN",
"Province":
"13",
"SousLocalite":
"",
"TypeVoie":
"",
"Region1":
"ﾄｳｷｮｳﾄ"
}
}
Errores
| HTTP | Tipo de error | Cuerpo de la respuesta |
|---|---|---|
| 200 |
Licence ausente o vacío
|
{} - resultado vacío, no se genera
ningún error
|
| 401 |
Licence incorrecta o caducada
|
unauthorized_client
|
| 400 |
Falta el parámetro CodePostal
|
Bad Request Parameters * not allowed
|
| 400 |
Error tipográfico en el nombre del parámetro
(p. ej. codepostal en lugar de
CodePostal)
|
Bad Request Parameters * not allowed
|
| 200 |
Código ISO de Pays no reconocido
(p. ej. AAA)
|
{} - resultado vacío, no se genera
ningún error
|
| 401 |
Formato de país no válido (p. ej. FRAN
en lugar de FRA)
|
unauthorized_country
|
Probar la API
Haga clic en el botón de abajo para probar este endpoint en vivo en su navegador.
Abrir consola
Búsqueda de calle (ADR)
Segundo paso del enfoque en embudo. A partir de un
IDLocalite de CP y un nombre de calle parcial,
devuelve las calles coincidentes. El IDVoie
de cada resultado alimenta el paso final: COMPL.
Solicitud
ADR admite tanto GET como POST.
{SERVER_ADDRESS} y {LICENCE_CODE}
son proporcionados por DQE al crear la cuenta.
{CITY_ID} se obtiene del campo
IDLocalite de la respuesta de CP cuando el usuario
selecciona una ciudad. Póngase en contacto con su gestor
de cuenta de DQE para obtener estas credenciales.
El valor de
Adresse debe estar codificado en
URL - p. ej. l'église → l%27%C3%A9glise.
GEThttps://{SERVER_ADDRESS}/ADR/?IDLocalite={CITY_ID}&Adresse={INPUT}&Pays={COUNTRY_CODE}&Licence={LICENCE_CODE}
Ejemplo cURL
Francia - IDLocalite del paso CP anterior
curl "https://{SERVER_ADDRESS}/ADR/?IDLocalite=75108&Adresse=bienfaisance&Pays=FRA&Licence={LICENCE_CODE}&Taille=38&Version=1.1"
fetch("https://{SERVER_ADDRESS}/ADR/?" +
new URLSearchParams({
IDLocalite: "75108",
Adresse: "bienfaisance",
Pays: "FRA",
Licence: "{LICENCE_CODE}",
Taille: "38",
Version: "1.1"
}))
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.get(
"https://{SERVER_ADDRESS}/ADR/",
params={
"IDLocalite": "75108",
"Adresse": "bienfaisance",
"Pays": "FRA",
"Licence": "{LICENCE_CODE}",
"Taille": "38",
"Version": "1.1",
},
)
print(response.json())
<?php
$params = http_build_query([
'IDLocalite' => '75108',
'Adresse' => 'bienfaisance',
'Pays' => 'FRA',
'Licence' => '{LICENCE_CODE}',
'Taille' => '38',
'Version' => '1.1',
]);
$ch = curl_init("https://{SERVER_ADDRESS}/ADR/?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
axios.get('https://{SERVER_ADDRESS}/ADR/',
{
params: {
IDLocalite: '75108',
Adresse: 'bienfaisance',
Pays: 'FRA',
Licence: '{LICENCE_CODE}',
Taille: '38',
Version: '1.1'
}
})
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String url = "https://{SERVER_ADDRESS}/ADR/"
+ "?IDLocalite=75108&Adresse=bienfaisance&Pays=FRA&Licence={LICENCE_CODE}&Taille=38&Version=1.1";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.GET()
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var url = "https://{SERVER_ADDRESS}/ADR/"
+
"?IDLocalite=75108&Adresse=bienfaisance&Pays=FRA&Licence={LICENCE_CODE}&Taille=38&Version=1.1";
var response = await client.GetAsync(url);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://{SERVER_ADDRESS}/ADR/" +
"?IDLocalite=75108&Adresse=bienfaisance&Pays=FRA&Licence={LICENCE_CODE}&Taille=38&Version=1.1"
resp, err := http.Get(url)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
POSThttps://{SERVER_ADDRESS}/ADR/
Envíe todos los parámetros en el cuerpo de la solicitud
usando
Content-Type: application/x-www-form-urlencoded.
La dirección del servidor permanece en la URL.
Ejemplo cURL
curl -X POST "https://{SERVER_ADDRESS}/ADR/"
\
-H "Content-Type: application/x-www-form-urlencoded"
\
-d "IDLocalite=75108" \
-d "Adresse=bienfaisance" \
-d "Pays=FRA" \
-d "Licence={LICENCE_CODE}"
fetch("https://{SERVER_ADDRESS}/ADR/", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded"
},
body: new URLSearchParams({
IDLocalite: "75108",
Adresse: "bienfaisance",
Pays: "FRA",
Licence: "{LICENCE_CODE}"
})
})
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.post(
"https://{SERVER_ADDRESS}/ADR/",
data={
"IDLocalite": "75108",
"Adresse": "bienfaisance",
"Pays": "FRA",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$ch = curl_init("https://{SERVER_ADDRESS}/ADR/");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'IDLocalite' => '75108',
'Adresse' => 'bienfaisance',
'Pays' => 'FRA',
'Licence' => '{LICENCE_CODE}',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
const qs = require('querystring');
axios.post('https://{SERVER_ADDRESS}/ADR/',
qs.stringify({
IDLocalite: '75108',
Adresse: 'bienfaisance',
Pays: 'FRA',
Licence: '{LICENCE_CODE}'
}))
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String form = "IDLocalite=75108&Adresse=bienfaisance&Pays=FRA&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{SERVER_ADDRESS}/ADR/"))
.header("Content-Type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(form))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var form = new Dictionary<string, string>
{
["IDLocalite"] = "75108",
["Adresse"] = "bienfaisance",
["Pays"] = "FRA",
["Licence"] = "{LICENCE_CODE}"
};
var response = await client.PostAsync(
"https://{SERVER_ADDRESS}/ADR/",
new FormUrlEncodedContent(form));
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
form := url.Values{}
form.Set("IDLocalite", "75108")
form.Set("Adresse", "bienfaisance")
form.Set("Pays", "FRA")
form.Set("Licence", "{LICENCE_CODE}")
resp, err := http.PostForm("https://{SERVER_ADDRESS}/ADR/",
form)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
Parámetros
| Parameter | Valor | Descripción | Obl. / Opc. |
|---|---|---|---|
| Licence |
{LICENCE_CODE}
|
Su clave de licencia DQE o token OAuth2. Póngase en contacto con soporte si aún no dispone de una. | Obligatorio |
| IDLocalite |
{CITY_ID}
|
Identificador de ciudad devuelto por CP en el
campo IDLocalite. Limita la búsqueda
de calles a la ciudad seleccionada.
|
Obligatorio |
| Adresse |
{INPUT}
|
Nombre de calle parcial introducido por el usuario. | Obligatorio |
| Pays |
{COUNTRY_CODE}
|
Código de país ISO 3166-1 alfa-3 para el ámbito
de búsqueda de la dirección. Ejemplo: FRA
o GBR.
|
Obligatorio |
| Taille |
{LENGTH}
|
Longitud máxima de caracteres para los campos
de dirección devueltos. Se aplica solo a direcciones
con caracteres latinos. Por defecto: 38.
Mínimo recomendado: 32.
|
Opcional |
| Instance |
{INSTANCE}
|
No se devuelve en los resultados de este endpoint - se puede omitir sin problema. | Opcional |
| Version=1.1 |
1.1
|
Si se establece en 1.1, completa
el campo LieuDit para los pueblos
pequeños. Sin él, los nombres de los pueblos
pequeños aparecen entre corchetes en el campo
Localite.
|
Opcional |
| Langue |
{LANGUAGE}
|
Filtra los resultados por idioma/escritura. JPN:
JP = Kanji · JK =
Katakana · EN = Romanizado. HKG:
EN · ZH. THA: EN
· TH. Consulte la
guía de idiomas.
|
Opcional |
Respuesta
Si la solicitud tiene éxito, la API devuelve un objeto JSON.
Las claves son números de clasificación de "1"
a "n", cada una asociada a un diccionario de
campos de calle.
| Field | Descripción | Francia | Internacional |
|---|---|---|---|
| label |
Cadena lista para mostrar en un desplegable de
autocompletado. Los números entre [corchetes]
indican que el número no se encontró en los datos
de referencia. Consulte
Campo Label - solo visualización
para notas de uso.
Use
label únicamente para completar el desplegable de sugerencias - nunca para almacenar la dirección.Ver guía de integración →
|
Not available | String (255) |
|
IDVoie also: CodeVoie |
Identificador único de la calle. Se usa como entrada para COMPL. | String (20) | String (20) |
| Voie | Nombre de la calle. | String (38) | String (150) |
| Saisie | Forma normalizada de la calle introducida. Puede diferir de la entrada original en mayúsculas/minúsculas o formato. | String (255) | String (255) |
| TypeVoie |
Tipo de vía (p. ej., RUE, AVENUE,
BOULEVARD). No se devuelve para
todos los conjuntos de datos internacionales.
|
String (20) | String (20) |
|
Numero also: Num |
Número de calle completo, incluyendo cualquier complemento (bis, ter, etc.). | String (38) | String (38) |
| NumSeul | Solo el número de calle, sin ningún complemento (bis, ter, etc.). | Not available | String (4) |
|
NbNumero also: Nbnumero |
Cuando el número consultado no se encuentra o
falta, devuelve el recuento total de números
de calle válidos para esta calle. Ambas claves
(NbNumero / Nbnumero)
se refieren al mismo valor. Puede ser una cadena
vacía cuando no corresponde.
|
String | String |
| ListeNumero | Lista de números de calle válidos separados por punto y coma. Contiene todos los números cuando no se introdujo ningún número o cuando el número introducido no se encontró; en caso contrario, contiene solo el número coincidente. | String (1024) | String (1024) |
| valid_num |
Indicador de validez del número de calle. 1
si el número existe en los datos de referencia,
0 en caso contrario. Devuelve una
cadena vacía para algunas direcciones internacionales
donde la validación a nivel de número no está
disponible.
|
Not available | Integer |
| CodePostal | Código postal de la dirección. | String (10) | String (10) |
| Localite | Nombre de la ciudad. | String (38) | String (50) |
| IDLocalite | Identificador único de la ciudad (código INSEE para Francia). | String (20) | String (20) |
| SousLocalite | Sublocalidad (distrito, barrio, suburbio). | Not available | String (50) |
| LieuDit |
Localidad con nombre. Se completa cuando
Version=1.1 se establece en la solicitud.
Puede completarse para direcciones internacionales.
|
String (38) | String (50) |
| Province |
Código ISO del estado o región administrativa
(p. ej. 17 para Japón).
|
Not available | String (50) |
| Region1 |
Etiqueta ISO del estado o región administrativa
(p. ej. ISHIKAWA para Japón).
|
Not available | String (50) |
| Region2 | Condado o nivel administrativo equivalente. | Not available | String (50) |
| Region3 | Condado o equivalente (nivel alternativo). | Not available | String (50) |
| Region4 | Información regional o administrativa adicional. | Not available | String (50) |
| Suburb | Suburbio o distrito. | Not available | String (50) |
| Thoroughfare | Vía dependiente. | Not available | UK only |
| Complement | Información adicional de la dirección (nombre del edificio, piso, etc.). La disponibilidad varía según el país - consulte la guía de integración. | Empty | String (50) |
| Complement2 | Segunda línea de sub-edificio. Se completa para ciertas direcciones internacionales cuando tanto un identificador de edificio como un identificador de sub-edificio (piso, apartamento, oficina) están disponibles como entradas separadas, y para ciertas direcciones CEDEX organizacionales. | Not available | String (50) |
| Entreprise | Nombre de la empresa asociada a la dirección. | String (38) | String (38) |
| Cedex |
Indicador CEDEX: 1 = dirección CEDEX,
0 = no CEDEX.
|
String (1) | String (1) |
| Latitude | Geocoordenadas de la dirección encontrada. No disponible para todos los países - consulte la cobertura. | String | String |
| Longitude | Geocoordenadas de la dirección encontrada. No disponible para todos los países - consulte la cobertura. | String | String |
| Roudis | Código Roudis. | String | Not available |
| Pays | Código de país ISO 3166-1 alfa-3. | String (3) | String (3) |
| Instance | Campo interno. | String | String |
Devuelto
con Version=1.1
¿Calle seleccionada sin número?
Ver guía de integración →
Ejemplo de respuesta
Ejemplo de respuesta - Francia (Rue de la Bienfaisance, 75008 París)
{
"1": {
"IDLocalite":
"75108",
"Saisie":
"bienfaisance",
"Pays":
"FRA",
"IDVoie":
"1454259",
"Voie":
"RUE DE LA BIENFAISANCE",
"Roudis":
"",
"ListeNumero":
"1;2;3;3B;4;6;7;7B;8;9;10;12;12B;15;16;17;19;20;21;23;25;26;27;28;29;30;32;33;34;35;36;37;39;40;41;42;43;44;45;46;47;48;50;51;52;52B;54",
"Numero":
"",
"TypeVoie":
"RUE",
"Instance":
"",
"Cedex":
"0",
"Num":
"",
"CodePostal":
"75008",
"NbNumero":
"47",
"Longitude":
"2.316451",
"LieuDit":
"",
"Latitude":
"48.876526",
"Localite":
"PARIS",
"CodeVoie":
"1454259",
"Complement":
"",
"Entreprise":
""
}
}
Ejemplo de respuesta - Japón (三田, 108-6390)
{
"1": {
"label":
"〒108-6390 東京都港区三田",
"valid_num": 1,
"Num":
"",
"Numero":
"",
"ListeNumero":
"",
"Nbnumero": 0,
"NbNumero": 0,
"NumSeul":
"",
"Saisie":
"三田",
"Pays":
"JPN",
"Complement":
"",
"Voie":
"三田",
"CodeVoie":
"558203",
"IDVoie":
"558203",
"IDLocalite":
"402573",
"Instance": 1,
"CodePostal":
"108-6390",
"Localite":
"港区",
"Province":
"13",
"LieuDit":
"",
"Longitude":
"",
"Latitude":
"",
"Region1":
"東京都",
"Region2":
"港区",
"Region3":
"",
"Suburb":
"",
"TypeVoie":
""
}
}
Errores
| HTTP | Tipo de error | Cuerpo de la respuesta |
|---|---|---|
| 200 |
Licence ausente o vacío
|
{} - resultado vacío, no se genera
ningún error
|
| 401 |
Licence incorrecta o caducada
|
unauthorized_client
|
| 400 |
Falta IDLocalite
|
Bad Request Parameters * not allowed
|
| 400 |
Falta Adresse
|
Bad Request Parameters * not allowed
|
| 400 |
Falta Pays
|
Bad Request Parameters * not allowed
|
| 400 |
Error tipográfico en el nombre del parámetro
(p. ej. una errata en Adresse o
IDLocalite)
|
Bad Request Parameters * not allowed
|
Probar la API
Haga clic en el botón de abajo para probar este endpoint en vivo en su navegador.
Abrir consola
Edificio (COMPL)
Paso final del enfoque en embudo. A partir de un IDVoie y un Numero de ADR, devuelve una lista de sugerencias de sub-edificio: nombres de edificios, números de piso, nombres de empresas, números de apartamento.
Solicitud
COMPL admite tanto GET como POST.
{SERVER_ADDRESS} y {LICENCE_CODE}
son proporcionados por DQE al crear la cuenta.
{STREET_ID} se obtiene del campo
IDVoie de la respuesta de ADR cuando el usuario
selecciona una calle. Póngase en contacto con su gestor de
cuenta de DQE para obtener estas credenciales.
GEThttps://{SERVER_ADDRESS}/COMPL/?IDVoie={STREET_ID}&IDNum={NUM}&Pays={COUNTRY_CODE}&Licence={LICENCE_CODE}
Ejemplo cURL
Francia - IDVoie del paso ADR anterior
curl "https://{SERVER_ADDRESS}/COMPL/?IDVoie=2408474&IDNum=1&Pays=FRA&Licence={LICENCE_CODE}"
fetch("https://{SERVER_ADDRESS}/COMPL/?"
+ new URLSearchParams({
IDVoie: "2408474",
IDNum: "1",
Pays: "FRA",
Licence: "{LICENCE_CODE}"
}))
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.get(
"https://{SERVER_ADDRESS}/COMPL/",
params={
"IDVoie": "2408474",
"IDNum": "1",
"Pays": "FRA",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$params = http_build_query([
'IDVoie' => '2408474',
'IDNum' => '1',
'Pays' => 'FRA',
'Licence' => '{LICENCE_CODE}',
]);
$ch = curl_init("https://{SERVER_ADDRESS}/COMPL/?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
axios.get('https://{SERVER_ADDRESS}/COMPL/',
{
params: {
IDVoie: '2408474',
IDNum: '1',
Pays: 'FRA',
Licence: '{LICENCE_CODE}'
}
})
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String url = "https://{SERVER_ADDRESS}/COMPL/"
+ "?IDVoie=2408474&IDNum=1&Pays=FRA&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.GET()
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var url = "https://{SERVER_ADDRESS}/COMPL/"
+
"?IDVoie=2408474&IDNum=1&Pays=FRA&Licence={LICENCE_CODE}";
var response = await client.GetAsync(url);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://{SERVER_ADDRESS}/COMPL/"
+
"?IDVoie=2408474&IDNum=1&Pays=FRA&Licence={LICENCE_CODE}"
resp, err := http.Get(url)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
Cuando el usuario no ha introducido un número de
calle,
envíe el parámetro IDNum vacío:
&IDNum=
POSThttps://{SERVER_ADDRESS}/COMPL/
Envíe todos los parámetros en el cuerpo de la solicitud
usando
Content-Type: application/x-www-form-urlencoded.
La dirección del servidor permanece en la URL.
Ejemplo cURL
curl -X POST "https://{SERVER_ADDRESS}/COMPL/"
\
-H "Content-Type: application/x-www-form-urlencoded"
\
-d "IDVoie=2408474" \
-d "IDNum=1" \
-d "Pays=FRA" \
-d "Licence={LICENCE_CODE}"
fetch("https://{SERVER_ADDRESS}/COMPL/",
{
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded"
},
body: new URLSearchParams({
IDVoie: "2408474",
IDNum: "1",
Pays: "FRA",
Licence: "{LICENCE_CODE}"
})
})
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.post(
"https://{SERVER_ADDRESS}/COMPL/",
data={
"IDVoie": "2408474",
"IDNum": "1",
"Pays": "FRA",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$ch = curl_init("https://{SERVER_ADDRESS}/COMPL/");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'IDVoie' => '2408474',
'IDNum' => '1',
'Pays' => 'FRA',
'Licence' => '{LICENCE_CODE}',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
const qs = require('querystring');
axios.post('https://{SERVER_ADDRESS}/COMPL/',
qs.stringify({
IDVoie: '2408474',
IDNum: '1',
Pays: 'FRA',
Licence: '{LICENCE_CODE}'
}))
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String form = "IDVoie=2408474&IDNum=1&Pays=FRA&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{SERVER_ADDRESS}/COMPL/"))
.header("Content-Type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(form))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var form = new Dictionary<string, string>
{
["IDVoie"] = "2408474",
["IDNum"] = "1",
["Pays"] = "FRA",
["Licence"] = "{LICENCE_CODE}"
};
var response = await client.PostAsync(
"https://{SERVER_ADDRESS}/COMPL/",
new FormUrlEncodedContent(form));
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
form := url.Values{}
form.Set("IDVoie", "2408474")
form.Set("IDNum", "1")
form.Set("Pays", "FRA")
form.Set("Licence", "{LICENCE_CODE}")
resp, err := http.PostForm("https://{SERVER_ADDRESS}/COMPL/",
form)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
Parámetros
| Parameter | Valor | Descripción | Obl. / Opc. |
|---|---|---|---|
| Licence |
{LICENCE_CODE}
|
Su clave de licencia DQE o token OAuth2. Póngase en contacto con soporte si aún no dispone de una. | Obligatorio |
| IDVoie |
{STREETID}
|
Identificador único de calle devuelto por ADR
en el campo IDVoie.
|
Obligatorio |
| IDNum |
{STREETNUMBER}
|
Número de calle seleccionado por el usuario -
corresponde al campo Numero de la
respuesta de ADR.
|
Obligatorio |
| Pays |
{COUNTRY_CODE}
|
Código de país ISO 3166-1 alfa-3 para el ámbito
de búsqueda de la dirección. Ejemplo: FRA
o GBR.
|
Obligatorio |
| Taille |
{LENGTH}
|
Longitud máxima de caracteres para los campos
de dirección devueltos. Se aplica solo a direcciones
con caracteres latinos. Un valor demasiado bajo
puede truncar los resultados. Por defecto: 38.
Mínimo recomendado: 32.
|
Opcional |
| Instance |
{INSTANCE}
|
No se devuelve en los resultados de este endpoint - se puede omitir sin problema. | Opcional |
Respuesta
La respuesta JSON es un diccionario cuyas claves están numeradas
de "1" a "n". Cada entrada contiene
un complemento de dirección.
La ausencia de datos de sub-edificio no es un error.Ver guía de integración →
| Field | Descripción | Francia | Internacional |
|---|---|---|---|
| Batiment | Etiqueta de complemento de edificio o apartamento. | String (38) | String (150) |
| CodePostal | Código postal asociado al complemento. | Not available | String (10) |
Ejemplo de respuesta
Ejemplo de respuesta - Francia (1 Rue de la Louisiane, 31200 Toulouse)
{
"1": {
"Batiment":
"BATIMENT D RESIDENCE ALLEE DES CEDRES"
},
"2": {
"Batiment":
"BATIMENT A RESIDENCE ALLEE DES CEDRES"
},
"3": {
"Batiment":
"BATIMENT B RESIDENCE ALLEE DES CEDRES"
},
"4": {
"Batiment":
"BATIMENT C RESIDENCE ALLEE DES CEDRES"
}
}
Ejemplo de respuesta - Internacional (GBR)
{
"1": {
"Batiment":
"Town Hall, Tameside Metropolitan Borough Council",
"CodePostal":
"M34 2AP"
},
"2": {
"Batiment":
"Victoria Park Community Association",
"CodePostal":
"M34 2AP"
}
}
Errores
| HTTP | Tipo de error | Cuerpo de la respuesta |
|---|---|---|
| 401 |
Parámetro Licence ausente o vacío
|
unauthorized_client
|
| 401 | Clave de licencia incorrecta o caducada |
unauthorized_client
|
| 400 |
Falta el parámetro IDVoie
|
Bad Request Parameters empty fields
|
| 400 |
Falta el parámetro IDNum
|
Bad Request Parameters empty fields
|
| 400 |
Falta el parámetro Pays
|
Bad Request Parameters empty fields
|
| 400 |
Error tipográfico en el nombre del parámetro
(p. ej. IdVoie en lugar de IDVoie)
|
Bad Request Parameters empty fields
|
Probar la API
Haga clic en el botón de abajo para probar este endpoint en vivo en su navegador.
Abrir consola
Ver también
Relacionada con