Autocompletado por embudo - API estándar
Autocompletado de direcciones en tres pasos mediante la API clásica. CP encuentra las ciudades coincidentes a partir de un código postal o un nombre de ciudad; ADR devuelve las calles dentro de la ciudad seleccionada; COMPL recupera las opciones de sub-edificio tras la selección de la calle.
Flujo de autocompletado en tres pasos
Formato de mayúsculas de la salida - El formato de mayúsculas sigue la norma postal del país correspondiente.
Búsqueda de ciudad (CP)
Primer paso del enfoque de 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 de cURL
Francia - Búsqueda por código postal
curl "https://{SERVER_ADDRESS}/CP/?CodePostal=75008&Alpha=True&Pays=FRA&Licence={LICENCE_CODE}"
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 de 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}"
Parámetros
| Parámetro | Valor | Descripción | Oblig. / Opc. |
|---|---|---|---|
| Licence | {LICENCE_CODE} |
Su clave de licencia de DQE o token OAuth2. Póngase en contacto con soporte si aún no dispone de una. | Obligatorio |
| CodePostal | {POSTAL_CODE} |
Entrada de código postal o nombre de ciudad. | Obligatorio |
| Pays | {COUNTRY_CODE} |
Código de país ISO 3166-1 alfa-3 para el ámbito de búsqueda de direcciones. Ejemplo: FRA o GBR. |
Obligatorio |
| Alpha | True |
Envíe siempre True. Parámetro obligatorio. |
Obligatorio |
| Instance | {INSTANCE} |
No se refleja en los resultados de este endpoint - se puede omitir sin problema. | Opcional |
| Etendue |
Y o N
|
Permite la búsqueda a partir de solo 2 caracteres en la entrada de código postal. Valor predeterminado: 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 = solo código postal y CEDEX · 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
Cuando la solicitud es exitosa, la API devuelve un objeto JSON. Las claves son números de rango de "1" a "n", cada uno asignado a un diccionario de campos de dirección.
Esquema de respuesta variable - Cuando
IDVoie está rellenado, Voie aparece en el JSON. Cuando solo se devuelve una ciudad, Voie está ausente. Utilice un IDVoie no vacío para detectar qué esquema 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 y 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.| Campo | Descripción | Francia | Internacional |
|---|---|---|---|
| Province | Código ISO de región o estado administrativo (p. ej. 17 para Japón). |
String (50) | String (50) |
| IDLocalite | Identificador único de 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). | Vacío | String (50) |
| LieuDit | Localidad denominada o aldea (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 coincidente. No disponible en todos los países - consulte la cobertura. | String | String |
| Longitude | Geocoordenadas de la localidad coincidente. No disponible en todos los países - consulte la cobertura. | String | String |
| IDVoie | Identificador único de calle. Se rellena solo cuando el código postal corresponde a una calle específica. Cuando está presente, puede omitir ADR y pasar IDVoie directamente a COMPL. |
String (20) | String (20) |
| Voie | Nombre de la calle. Solo está presente en la respuesta cuando IDVoie está rellenado. |
String (38) | String (150) |
| NbNumero | Número total de números de calle en la calle coincidente. Se rellena solo cuando IDVoie está presente; vacío en caso contrario. |
String | String |
| ListeNumero | Lista de números de calle válidos separados por punto y coma para la calle coincidente. Siempre contiene todos los números cuando está presente; vacío 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 en todos los conjuntos de datos internacionales. |
String (20) | String (20) |
| Complement | Información adicional de la dirección. | Vacío | 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 de región o estado administrativo (p. ej. ISHIKAWA para Japón). |
No disponible | String (50) |
| Region2 | Provincia o nivel administrativo equivalente. | No disponible | String (50) |
| Region3 | Provincia o equivalente (nivel alternativo). | No disponible | String (50) |
| Region4 | Información regional o administrativa adicional. | No disponible | 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, sin error |
| 401 |
Licence incorrecto o caducado
|
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, sin 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 de embudo. A partir de un IDLocalite obtenido 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 de 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"
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 de 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}"
Parámetros
| Parámetro | Valor | Descripción | Oblig. / Opc. |
|---|---|---|---|
| Licence | {LICENCE_CODE} |
Su clave de licencia de 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 direcciones. Ejemplo: FRA o GBR. |
Obligatorio |
| Taille | {LENGTH} |
Longitud máxima de caracteres para los campos de dirección devueltos. Se aplica únicamente a direcciones con caracteres latinos. Valor predeterminado: 38. Mínimo recomendado: 32. |
Opcional |
| Instance | {INSTANCE} |
No se refleja en los resultados de este endpoint - se puede omitir sin problema. | Opcional |
| Version=1.1 | 1.1 |
Si se establece en 1.1, rellena el campo LieuDit para poblaciones pequeñas. Sin él, los nombres de poblaciones pequeñas 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
Cuando la solicitud es exitosa, la API devuelve un objeto JSON. Las claves son números de rango de "1" a "n", cada uno asignado a un diccionario de campos de calle.
| Campo | 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.
Utilice
label únicamente para rellenar el desplegable de sugerencias - nunca para almacenar la dirección. Ver guía de integración →
|
No disponible | String (255) |
| IDVoie also: CodeVoie |
Identificador único de 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 entrada de calle enviada. 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 en 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 | Número de calle únicamente, sin ningún complemento (bis, ter, etc.). | No disponible | String (4) |
| NbNumero also: Nbnumero |
Cuando el número consultado no se encuentra o falta, devuelve el número total de números de calle válidos para esta calle. Ambas claves (NbNumero / Nbnumero) hacen referencia al mismo valor. Puede ser una cadena vacía cuando no aplica. |
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 encuentra; 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. |
No disponible | 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 ciudad (código INSEE para Francia). | String (20) | String (20) |
| SousLocalite | Sublocalidad (distrito, barrio, suburbio). | No disponible | String (50) |
| LieuDit | Localidad denominada. Se rellena cuando Version=1.1 se establece en la solicitud. Puede rellenarse para direcciones internacionales. |
String (38) | String (50) |
| Province | Código ISO de región o estado administrativo (p. ej. 17 para Japón). |
No disponible | String (50) |
| Region1 | Etiqueta ISO de región o estado administrativo (p. ej. ISHIKAWA para Japón). |
No disponible | String (50) |
| Region2 | Provincia o nivel administrativo equivalente. | No disponible | String (50) |
| Region3 | Provincia o equivalente (nivel alternativo). | No disponible | String (50) |
| Region4 | Información regional o administrativa adicional. | No disponible | String (50) |
| Suburb | Suburbio o distrito. | No disponible | String (50) |
| Thoroughfare | Calle dependiente. | No disponible | Solo Reino Unido |
| 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. | Vacío | String (50) |
| Complement2 | Segunda línea de sub-edificio. Se rellena 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. | No disponible | 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 coincidente. No disponible en todos los países - consulte la cobertura. | String | String |
| Longitude | Geocoordenadas de la dirección coincidente. No disponible en todos los países - consulte la cobertura. | String | String |
| Roudis | Código Roudis. | String | No disponible |
| 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, sin error |
| 401 |
Licence incorrecto o caducado
|
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. error ortográfico de 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 de embudo. A partir de un IDVoie y un Numero obtenidos 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 de cURL
Francia - IDVoie del paso ADR anterior
curl "https://{SERVER_ADDRESS}/COMPL/?IDVoie=2408474&IDNum=1&Pays=FRA&Licence={LICENCE_CODE}"
Cuando el usuario no haya 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 de 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}"
Parámetros
| Parámetro | Valor | Descripción | Oblig. / Opc. |
|---|---|---|---|
| Licence | {LICENCE_CODE} |
Su clave de licencia de 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 direcciones. Ejemplo: FRA o GBR. |
Obligatorio |
| Taille | {LENGTH} |
Longitud máxima de caracteres para los campos de dirección devueltos. Se aplica únicamente a direcciones con caracteres latinos. Establecer un valor demasiado bajo puede truncar los resultados. Valor predeterminado: 38. Mínimo recomendado: 32. |
Opcional |
| Instance | {INSTANCE} |
No se refleja 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 →
| Campo | Descripción | Francia | Internacional |
|---|---|---|---|
| Batiment | Etiqueta de complemento de edificio o apartamento. | String (38) | String (150) |
| CodePostal | Código postal asociado al complemento. | No disponible | 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
Véase también
Relacionada con