Autocompletado - Línea única - API estándar
Autocompletado de direcciones en dos pasos mediante la API Classic. SINGLEV2 devuelve sugerencias de direcciones clasificadas a partir de una entrada de texto libre; COMPLV2 recupera las opciones de subedificio después de que el usuario seleccione una sugerencia.
Flujo de autocompletado en dos pasos
El usuario escribe libremente; SINGLEV2 devuelve sugerencias clasificadas en tiempo real. Tras la selección, COMPLV2 recupera las opciones de subedificio (nombres de edificio, números de planta, números de apartamento).
Mayúsculas de salida - El uso de mayúsculas sigue la norma postal del país correspondiente.
SINGLEV2
Endpoint de la API estándar para el autocompletado de direcciones. Acepta una entrada de texto libre parcial o completa y devuelve una lista clasificada de sugerencias de direcciones. Cada sugerencia incluye un IDVoie que se utiliza como entrada para COMPLV2 para completar el subedificio.
Cuándo usar SINGLEV2 Utilice este endpoint para sugerir direcciones mientras el usuario escribe. Gestiona entradas parciales (fragmento de calle, código postal, nombre de ciudad) y devuelve todos los campos estructurados listos para rellenar un formulario. Para verificar que una dirección ya completa es válida y entregable, utilice RNVP en su lugar. Ver guía de integración →
Solicitud
Se admiten 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.
La dirección de entrada debe estar codificada en URL - p. ej.
l'église → l%27%C3%A9glise. GEThttps://{SERVER_ADDRESS}/SINGLEV2/?Adresse={INPUT}&Pays={COUNTRY_CODE}&Licence={LICENCE_CODE}
Ejemplos de cURL
Francia - entrada parcial
curl "https://{SERVER_ADDRESS}/SINGLEV2/?Adresse=8%20rue%20Victor%20Hugo%20Levall&Pays=FRA&Licence={LICENCE_CODE}&Taille=38&NbMax=20&Version=1"
Japón - Kanji, con el parámetro Langue
curl "https://{SERVER_ADDRESS}/SINGLEV2/?Adresse=108-6390&Pays=JPN&Taille=38&Langue=JP&Version=1&Licence={LICENCE_CODE}"
POSThttps://{SERVER_ADDRESS}/SINGLEV2/
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
Francia - entrada parcial
curl -X POST "https://{SERVER_ADDRESS}/SINGLEV2/" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "Adresse=8+rue+Victor+Hugo+Levall" \
-d "Pays=FRA" \
-d "Licence={LICENCE_CODE}" \
-d "Taille=38" \
-d "NbMax=20" \
-d "Version=1"
Parámetros
| Parámetro | Valor | Descripción | Obl. / 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 |
| Adresse | {INPUT} |
Cadena de dirección de texto libre introducida por el usuario. Acepta una entrada parcial: fragmento de calle, número de calle, código postal o nombre de ciudad. Debe estar codificada en URL. No se requiere formato con separador de barra vertical - pase la cadena tal cual se escribió. | 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 las sugerencias de dirección devueltas. Se aplica únicamente a direcciones con caracteres latinos. Si se establece un valor demasiado bajo, los resultados pueden truncarse. Valor predeterminado: 38. Mínimo recomendado: 32. |
Opcional |
| NbMax | {NB} |
Número máximo de sugerencias de dirección devueltas. Valor predeterminado: 20. |
Opcional |
| Version | 1 |
Cuando se establece en 1, el tipo de vía se extrae de la clave Voie y se devuelve en un campo específico TypeVoie. Sin este parámetro, el tipo de vía permanece dentro de Voie (por ejemplo, RUE DE LA PAIX) y TypeVoie queda vacío. |
Opcional |
| Instance | {INSTANCE} |
No se refleja en los resultados de este endpoint - se puede omitir sin problema. | Opcional |
| Langue | {LANGUAGE} |
Filtra los resultados por idioma/alfabeto (por ejemplo, JPN: JP = kanji · JK = katakana · EN = romanizado). Consulte la guía de idiomas. |
Opcional |
| Filter | {FILTER} |
Solo Francia. Filtra las direcciones CEDEX: 1 todas las direcciones; 2 solo sin CEDEX; 3 solo CEDEX. |
Opcional |
Respuesta
Si la solicitud se realiza correctamente, la API devuelve un objeto JSON. Las claves son números de clasificación de "1" a "n", cada uno asociado a un diccionario de campos de dirección. El primer resultado es la coincidencia más cercana a la entrada.
Lectura funcional: Considere la respuesta como una lista clasificada de sugerencias de dirección.
"1" es la mejor coincidencia; los números más altos son candidatos alternativos. El campo label contiene la cadena lista para mostrar en su menú desplegable de autocompletado - todo lo demás le proporciona los componentes estructurados para rellenar los campos del formulario.| Clave | Descripción | Francia | Internacional |
|---|---|---|---|
| label | Cadena lista para mostrar en un menú 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 para visualización para más información sobre su uso.
Utilice
label únicamente para rellenar el menú desplegable de sugerencias - nunca para guardar la dirección. Ver guía de integración →
|
String (255) | String (255) |
| Voie | Nombre de la calle. | String (38) | String (150) |
| TypeVoie | Tipo de vía (por ejemplo, RUE, AVENUE, BOULEVARD). Solo se completa cuando se establece Version=1; en ese caso, el tipo de vía se elimina de Voie y se devuelve aquí en su lugar. |
String (20) | String (20) |
| Numero | Número de calle completo, incluido cualquier complemento (bis, ter, etc.). | String (38) | String (38) |
| Num | Alias de Numero. Se mantiene por compatibilidad - se recomienda usar Numero. |
String (38) | String (38) |
| NumSeul | Solo el número de calle, sin ningún complemento (bis, ter, etc.). | String (4) | 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. Puede ser una cadena vacía para algunas direcciones internacionales en las que este dato no está disponible. | String | String |
| 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 en las que la validación a nivel de número no está disponible. |
Integer | Integer |
| 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 únicamente el número coincidente. | String (1024) | String (1024) |
| IDVoie also: CodeVoie |
Identificador único de la calle. Se utiliza como entrada para COMPLV2. CodeVoie se mantiene por compatibilidad. Se recomienda usar IDVoie en las nuevas integraciones. | String (20) | String (20) |
| CodePostal | Código postal de la dirección. | String (10) | String (10) |
| Localite | Nombre de la ciudad. | String (38) | String (50) |
| SousLocalite | Sublocalidad (distrito, barrio, suburbio). | Vacío | String (50) |
| LieuDit | Localidad con nombre propio o aldea (Francia) o campo equivalente a nivel de distrito (internacional). La disponibilidad varía según el país. | String (38) | String (50) |
| IDLocalite | Identificador único de la ciudad (código INSEE para Francia). | String (20) | String (20) |
| Province | Código ISO de la región o estado administrativo (por ejemplo, 17 para Japón). |
No disponible | String (50) |
| Region1 | Etiqueta ISO de la región o estado administrativo (por ejemplo, ISHIKAWA para Japón). |
No disponible | String (50) |
| Region2 | Condado o nivel administrativo equivalente. | No disponible | String (50) |
| Region3 | Condado 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) |
| Complement | Información adicional de la dirección (nombre del edificio, planta, 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 subedificio. Se completa para determinadas direcciones internacionales cuando existen tanto un identificador de edificio como un identificador de subedificio (planta, apartamento, oficina) como entradas separadas, y para determinadas direcciones CEDEX organizativas. | No disponible | String (50) |
| Entreprise | Nombre de la empresa asociada a la dirección. | String (38) | String (38) |
| Thoroughfare | Vía dependiente. | No disponible | Solo Reino Unido |
| Pays | Código de país ISO 3166-1 alfa-3. | String (3) | String (3) |
| Latitude | Geocoordenadas de la dirección coincidente. No disponible para todos los países - consulte la cobertura. | No disponible | String |
| Longitude | Geocoordenadas de la dirección coincidente. No disponible para todos los países - consulte la cobertura. | No disponible | String |
| Saisie | Forma normalizada de la dirección enviada. Puede diferir de la entrada original en el uso de mayúsculas o el formato. No se completa para todos los países. | String (255) | String (255) |
| Instance | Campo interno. | Vacío | String |
Se completa con Version=1
¿Calle seleccionada sin número? Ver guía de integración →
Ejemplo de respuesta
Reino Unido - entrada "Abbey Road NW10 7TJ London"
{
"1": {
"label": "Abbey Road (West London Waste)|NW10 7TJ LONDON",
"valid_num": 1,
"Num": "",
"Numero": "",
"ListeNumero": "",
"Nbnumero": 0,
"NbNumero": 0,
"NumSeul": "",
"Saisie": "ABBEY ROAD NW10 7TJ LONDON",
"Pays": "GBR",
"Complement": "",
"Voie": "Abbey Road",
"CodeVoie": "7831549_NW107TJ",
"IDVoie": "7831549_NW107TJ",
"IDLocalite": "1745994",
"Instance": 1,
"CodePostal": "NW10 7TJ",
"Localite": "LONDON",
"Province": "",
"LieuDit": "",
"Longitude": "",
"Latitude": "",
"Suburb": "",
"TypeVoie": "",
"Entreprise": "West London Waste",
"Thoroughfare": ""
}
}
Japón - entrada "三田", Langue=JP
{
"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": ""
},
"2": {
"label": "〒942-0054 新潟県上越市三田",
"valid_num": 1,
"Num": "",
"Numero": "",
"ListeNumero": "",
"Nbnumero": 0,
"NbNumero": 0,
"NumSeul": "",
"Saisie": "三田",
"Pays": "JPN",
"Complement": "",
"Voie": "三田",
"CodeVoie": "537719",
"IDVoie": "537719",
"IDLocalite": "387092",
"Instance": 1,
"CodePostal": "942-0054",
"Localite": "上越市",
"Province": "15",
"LieuDit": "",
"Longitude": "",
"Latitude": "",
"Region1": "新潟県",
"Region2": "上越市",
"Region3": "",
"Suburb": "",
"TypeVoie": ""
}
// ... 18 more results
}
Errores
| HTTP | Tipo de error | Cuerpo de la respuesta |
|---|---|---|
| 400 | Falta o está vacío Licence
|
Bad Request Parameters empty fields |
| 401 | Clave de licencia no válida o no autorizada | unauthorized_client |
| 400 | Falta o está vacío Adresse
|
Bad Request Parameters empty fields |
| 400 | Falta o está vacío Pays
|
Bad Request Parameters empty fields |
| 400 | Nombre de parámetro no reconocido (por ejemplo, un error tipográfico en Adresse) |
Bad Request Parameters empty fields |
Probar la API
Haga clic en el botón siguiente para probar este endpoint en directo en su navegador.
Abrir consola
COMPLV2
Segundo paso del enfoque de línea única. A partir de un ID de calle y un número de calle seleccionados de un resultado de SINGLEV2, devuelve una lista de sugerencias de subedificio: nombres de edificio, números de planta, nombres de empresa, números de apartamento.
Cuándo usar COMPLV2 Utilice COMPLV2 después de que el usuario haya seleccionado una calle de SINGLEV2. Pase los valores
IDVoie e IDNum devueltos por SINGLEV2 para obtener opciones detalladas de subedificio. Si no existen opciones de subedificio para la dirección, no se devuelve ninguna entrada numerada.Solicitud
Se admiten tanto GET como POST.
{SERVER_ADDRESS} y {LICENCE_CODE} son proporcionados por DQE al crear la cuenta. {STREET_ID} se obtiene de la respuesta de SINGLEV2. Póngase en contacto con su gestor de cuenta de DQE para obtener estas credenciales.
GEThttps://{SERVER_ADDRESS}/COMPLV2/?IDVoie={STREET_ID}&IDNum={NUM}&Pays={COUNTRY_CODE}&Licence={LICENCE_CODE}
Ejemplo de cURL
Francia
curl "https://{SERVER_ADDRESS}/COMPLV2/?IDVoie=1454602&IDNum=20&Pays=FRA&Licence={LICENCE_CODE}"
POSThttps://{SERVER_ADDRESS}/COMPLV2/
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
Francia
curl -X POST "https://{SERVER_ADDRESS}/COMPLV2/" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "IDVoie=1454602" \
-d "IDNum=20" \
-d "Pays=FRA" \
-d "Licence={LICENCE_CODE}"
Parámetros
| Parámetro | Valor | Descripción | Obl. / 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 la calle devuelto por SINGLEV2 en el campo IDVoie o CodeVoie. |
Obligatorio |
| IDNum | {STREETNUMBER} |
Número de calle seleccionado por el usuario - corresponde al campo Numero de la respuesta de SINGLEV2. |
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 únicamente a direcciones con caracteres latinos. Si se establece un valor demasiado bajo, los resultados pueden truncarse. Valor predeterminado: 38. Mínimo recomendado: 32. |
Opcional |
| Filter | {FILTER} |
Para Estados Unidos: filtra las sugerencias de complemento según lo que haya escrito el usuario. Pase el tipo de complemento parcial introducido (por ejemplo, FL, STE, RM) - solo se devolverán las entradas de complemento que coincidan con ese valor. |
Opcional |
Respuesta
Si la solicitud se realiza correctamente, la API devuelve un objeto JSON con dos tipos de claves. Las claves numeradas ("1" a "n") representan cada una una opción de subedificio. Las claves geográficas de nivel raíz (Latitude, Longitude) proporcionan las geocoordenadas de la dirección coincidente. La cobertura de geocodificación varía según el país - consulte Cobertura geográfica.
No disponer de datos de subedificio no es un error. Ver guía de integración →
| Clave | Descripción | Francia | Internacional |
|---|---|---|---|
| Entradas numeradas ("1" a "n") - una por cada opción de subedificio | |||
| Batiment | Etiqueta de dirección adicional (nombre de edificio, planta, apartamento, etc.). | String (38) | String (150) |
| CodePostal | Código postal específico de esta subunidad, cuando esté disponible (por ejemplo, ZIP+4 para EE. UU.). | No disponible | String (10) |
| Campos geográficos de nivel raíz | |||
| Latitude | Geocoordenadas de la dirección coincidente. No disponible para todos los países - consulte la cobertura. | String | String |
| Longitude | Geocoordenadas de la dirección coincidente. No disponible para todos los países - consulte la cobertura. | String | String |
| Nivel raíz - opcional, solo Francia (requiere suscripción Iris/Ilot) | |||
| Status_IrisIlot | Origen de los códigos IRIS/Ilot (por ejemplo, INSEE). |
String (5) | No disponible |
| ilot | Código de Îlot. | String (9) | No disponible |
| iris | Código IRIS. | String (9) | No disponible |
Ejemplo de respuesta
Francia
{
"1": { "Batiment": "BATIMENT A" },
"2": { "Batiment": "BATIMENT B" },
"3": { "Batiment": "BATIMENT C" },
"4": { "Batiment": "BATIMENT D" },
"5": { "Batiment": "BATIMENT E" },
"Latitude": "48.879024",
"Longitude": "2.333291"
}
Errores
| HTTP | Tipo de error | Cuerpo de la respuesta |
|---|---|---|
| 400 | Falta o está vacío Licence
|
Bad Request Parameters empty fields |
| 500 | Clave de licencia no válida o no autorizada |
{} (objeto JSON vacío) |
| 400 | Falta IDVoie
|
400 Bad Request |
| 400 | Falta Pays
|
400 Bad Request |
| 400 | Error tipográfico en el nombre del parámetro (clave no reconocida) | 400 Bad Request |
Probar la API
Haga clic en el botón siguiente para probar este endpoint en directo en su navegador.
Abrir consola
Ver también
Relacionada con