Address API - Autocompletado desde una sola línea (RESTful)

Autocompletado - Línea única - RESTful

Autocompletado de direcciones en dos pasos mediante la API RESTful. single devuelve sugerencias de direcciones clasificadas a partir de una entrada de texto libre; compl recupera las opciones de subedificio después de que el usuario seleccione una sugerencia.

Flujo de autocompletado en dos pasos

El usuario escribe libremente; /single/ devuelve sugerencias clasificadas en tiempo real. Tras la selección, /compl/ recupera las opciones de subedificio (nombres de edificio, números de planta, números de apartamento).

Paso 1/single/Autocompletado de texto libre → Paso 2/compl/Detalles de edificio y apartamento

Mayúsculas de salida - El uso de mayúsculas sigue la norma postal del país correspondiente.

single

Ir a Solicitud Parámetros Respuesta Ejemplo Errores ▶ Probar la API

Endpoint RESTful 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 StreetId que se utiliza como entrada para compl para completar el subedificio.

Cuándo usar single 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 CheckAddress en su lugar. Ver guía de integración →

Solicitud

Se admiten tanto GET como POST.

{SERVER_ADDRESS}, {VERSION} 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.

GET POST

GEThttps://{SERVER_ADDRESS}/{VERSION}/single/?Address={INPUT}&Country={COUNTRY_CODE}&Licence={LICENCE_CODE}

Ejemplos de cURL

Francia - entrada parcial

curl "https://{SERVER_ADDRESS}/v1/single/?Address=8%20rue%20Victor%20Hugo%20Levall&Country=FRA&Length=38&Limit=20&Version=1&Licence={LICENCE_CODE}"

Japón - Kanji, con el parámetro Langue

curl "https://{SERVER_ADDRESS}/v1/single/?Address=108-6390&Country=JPN&Length=38&Langue=JP&Version=1&Licence={LICENCE_CODE}"

POSThttps://{SERVER_ADDRESS}/{VERSION}/single/

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}/v1/single/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "Address=8+rue+Victor+Hugo+Levall" \
  -d "Country=FRA" \
  -d "Length=38" \
  -d "Limit=20" \
  -d "Version=1" \
  -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
Address	`{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
Country	`{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
Length	`{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
Limit	`{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 `Street` y se devuelve en un campo específico `StreetType`. Sin este parámetro, el tipo de vía permanece dentro de `Street` (por ejemplo, RUE DE LA PAIX) y `StreetType` queda vacío.	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 respuesta es un objeto JSON con dos claves de nivel superior: Found (entero) y Addresses (matriz de objetos de sugerencia de dirección, hasta Limit elementos). 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. Addresses[0] es la mejor coincidencia; los elementos posteriores de la matriz 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.

Nivel superior

Clave	Descripción	Tipo
Found	Número de objetos de sugerencia de dirección devueltos.	Integer
Addresses	Matriz de objetos de sugerencia de dirección.	Array

Objeto de sugerencia de dirección - `Addresses[n]`

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)
Street	Nombre de la calle.	String (38)	String (150)
StreetType	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 `Street` y se devuelve aquí en su lugar.	String (20)	String (20)
StreetNumber	Número de calle completo, incluido cualquier complemento (bis, ter, etc.).	String (38)	String (38)
StreetNumberOnly	Solo el número de calle, sin ningún complemento (bis, ter, etc.).	String (4)	String (4)
StreetNumberListCount	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
IsValidStreetNumber	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
StreetNumberList	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)
StreetId	Identificador único de la calle. Se utiliza como entrada para compl.	String (20)	String (20)
PostalCode	Código postal de la dirección.	String (10)	String (10)
City	Nombre de la ciudad.	String (38)	String (50)
Hamlet	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)
SubLocality	Sublocalidad (distrito, barrio, suburbio).	Vacío	String (50)
SpecialDistribution	No se utiliza. Siempre se devuelve como una cadena vacía.	String	String
CityId	Identificador único de la ciudad (código INSEE para Francia).	String (20)	String (20)
StateCode	Código ISO de la región o estado administrativo (por ejemplo, `17` para Japón).	Vacío	String (50)
StateLabel	Etiqueta ISO de la región o estado administrativo (por ejemplo, `ISHIKAWA` para Japón).	No disponible	String (50)
AdministrativeArea	Condado o nivel administrativo equivalente.	Vacío	String (50)
Suburb	Suburbio o distrito.	Vacío	String (50)
AdditionalAddress	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)
Company	Nombre de la empresa asociada a la dirección.	String (38)	String (38)
Input	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)
Country	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.	String	String
Longitude	Geocoordenadas de la dirección coincidente. No disponible para todos los países - consulte la cobertura.	String	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"

{
  "Found": 1,
  "Addresses": [
    {
      "PostalCode":           "NW10 7TJ",
      "City":                 "LONDON",
      "Hamlet":               "",
      "SpecialDistribution":  "",
      "Country":              "GBR",
      "StateCode":            "",
      "SubLocality":          "",
      "CityId":               "1745994",
      "Input":                "ABBEY ROAD NW10 7TJ LONDON",
      "Label":                "Abbey Road (West London Waste)|NW10 7TJ LONDON",
      "AdditionalAddress":    "",
      "StreetNumber":         "",
      "StreetType":           "",
      "Street":               "Abbey Road",
      "StreetId":             "7831549_NW107TJ",
      "IsValidStreetNumber":  1,
      "StreetNumberListCount":0,
      "StreetNumberList":     "",
      "StreetNumberOnly":     "",
      "StateLabel":           "",
      "AdministrativeArea":   "",
      "Suburb":               "",
      "Company":              "West London Waste",
      "Latitude":             "",
      "Longitude":            "" }
  ]
}

Japón - entrada "三田", Langue=JP

{
  "Found": 20,
  "Addresses": [
    {
      "PostalCode":           "108-6390",
      "City":                 "港区",
      "Hamlet":               "",
      "SpecialDistribution":  "",
      "Country":              "JPN",
      "StateCode":            "13",
      "SubLocality":          "",
      "CityId":               "402573",
      "Input":                "三田",
      "Label":                "〒108-6390 東京都港区三田",
      "AdditionalAddress":    "",
      "StreetNumber":         "",
      "StreetType":           "",
      "Street":               "三田",
      "StreetId":             "558203",
      "IsValidStreetNumber":  1,
      "StreetNumberListCount":0,
      "StreetNumberList":     "",
      "StreetNumberOnly":     "",
      "StateLabel":           "東京都",
      "AdministrativeArea":   "港区",
      "Suburb":               "",
      "Company":              "",
      "Latitude":             "",
      "Longitude":            "" },
    {
      "PostalCode":           "942-0054",
      "City":                 "上越市",
      "Hamlet":               "",
      "SpecialDistribution":  "",
      "Country":              "JPN",
      "StateCode":            "15",
      "SubLocality":          "",
      "CityId":               "387092",
      "Input":                "三田",
      "Label":                "〒942-0054 新潟県上越市三田",
      "AdditionalAddress":    "",
      "StreetNumber":         "",
      "StreetType":           "",
      "Street":               "三田",
      "StreetId":             "537719",
      "IsValidStreetNumber":  1,
      "StreetNumberListCount":0,
      "StreetNumberList":     "",
      "StreetNumberOnly":     "",
      "StateLabel":           "新潟県",
      "AdministrativeArea":   "上越市",
      "Suburb":               "",
      "Company":              "",
      "Latitude":             "",
      "Longitude":            "" }
    // ... 18 more results
  ]
}

Errores

El endpoint RESTful devuelve un cuerpo de error JSON estructurado con un código de estado HTTP, un mensaje y un identificador de error.

HTTP	Tipo de error	Cuerpo de la respuesta
400	Falta el parámetro `Licence`	{"status":400,"message":"Missing parameters","details":"Licence","error":"bad request"}
400	El parámetro `Licence` está vacío	{"status":400,"message":"Licence must be filled","details":"Empty","error":"bad request"}
401	Número de licencia incorrecto	{"status":401,"message":"Your licence is not allowed to cover this functionnality","details":"{WRONG}","error":"unauthorized_client"}
400	Falta el parámetro `Address`	{"status":400,"message":"Missing parameters","details":"Address","error":"bad request"}
400	Falta el parámetro `Country`	{"status":400,"message":"Missing parameters","details":"Country","error":"bad request"}
400	El parámetro `Country` está vacío	{"status":400,"message":"Country must be filled","details":"Empty","error":"bad request"}
400	Error tipográfico en el nombre del parámetro	{"status":400,"message":"Missing parameters","details":"Address","error":"bad request"}

Probar la API

Haga clic en el botón siguiente para probar este endpoint en directo en su navegador.

Abrir consola

compl

Ir a Solicitud Parámetros Respuesta Ejemplo Errores ▶ Probar la API

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 single, devuelve una lista de sugerencias de subedificio: nombres de edificio, números de planta, nombres de empresa, números de apartamento.

Cuándo usar compl Utilice compl después de que el usuario haya seleccionado una calle de single. Pase los valores StreetId y StreetNumber devueltos por single 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}, {VERSION} y {LICENCE_CODE} son proporcionados por DQE al crear la cuenta. {STREETID} se obtiene de la respuesta de single. Póngase en contacto con su gestor de cuenta de DQE para obtener estas credenciales.

GET POST

GEThttps://{SERVER_ADDRESS}/{VERSION}/compl/?StreetId={STREETID}&StreetNumber={STREETNUMBER}&Country={COUNTRY_CODE}&Licence={LICENCE_CODE}

Ejemplo de cURL

Francia

curl "https://{SERVER_ADDRESS}/v1/compl/?StreetId=1454602&StreetNumber=20&Country=FRA&Licence={LICENCE_CODE}"

POSThttps://{SERVER_ADDRESS}/{VERSION}/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

Francia

curl -X POST "https://{SERVER_ADDRESS}/v1/compl/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "StreetId=1454602" \
  -d "StreetNumber=20" \
  -d "Country=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
StreetId	`{STREETID}`	Identificador único de la calle devuelto por single en el campo `StreetId`.	Obligatorio
StreetNumber	`{STREETNUMBER}`	Número de calle seleccionado por el usuario - corresponde al campo `StreetNumber` de la respuesta de single.	Obligatorio
Country	`{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
Length	`{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
Search	`{SEARCH}`	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 respuesta es un objeto JSON con dos claves de nivel superior: Found y AdditionalAddresses (matriz), además de un objeto Geolocalisation. 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
Found	Número de complementos de dirección encontrados.	Integer	Integer
AdditionalAddresses	Matriz de objetos de dirección adicionales.	Array	Array
AdditionalAddresses[0]. AdditionalAddress	Etiqueta de dirección adicional (nombre de edificio, planta, apartamento, etc.).	String (38)	String (150)
AdditionalAddresses[0]. PostalCode	Código postal específico de esta subunidad, cuando esté disponible (por ejemplo, ZIP+4 para EE. UU.).	No disponible	String (10)
Geolocalisation	Información de geolocalización de la dirección.	Object	Object
Geolocalisation. Latitude	Geocoordenadas de la dirección coincidente. No disponible para todos los países - consulte la cobertura.	String	String
Geolocalisation. Longitude	Geocoordenadas de la dirección coincidente. No disponible para todos los países - consulte la cobertura.	String	String

Ejemplo de respuesta

Francia

{
  "Found": 5,
  "AdditionalAddresses": [
    { "AdditionalAddress": "BATIMENT A", "PostalCode": "" },
    { "AdditionalAddress": "BATIMENT B", "PostalCode": "" },
    { "AdditionalAddress": "BATIMENT C", "PostalCode": "" },
    { "AdditionalAddress": "BATIMENT D", "PostalCode": "" },
    { "AdditionalAddress": "BATIMENT E", "PostalCode": "" }
  ],
  "Geolocalisation": {
    "Latitude":  "48.879024",
    "Longitude": "2.333291" }
}

Errores

HTTP	Tipo de error	Cuerpo de la respuesta
400	Falta `StreetId`	{"status":400,"message":"Missing parameters","details":"StreetId","error":"bad request"}
400	Falta `StreetNumber`	{"status":400,"message":"Missing parameters","details":"StreetNumber","error":"bad request"}
400	Falta `Country`	{"status":400,"message":"Missing parameters","details":"Country","error":"bad request"}
400	Falta `Licence`	{"status":400,"message":"Missing parameters","details":"Licence","error":"bad request"}
401	Cliente no autorizado (licencia no válida, caducada o fuera de ámbito)	{"status":401,"message":"Your licence is not allowed to cover this functionnality","details":"{INVALID_LICENCE}","error":"unauthorized_client"}

Probar la API

Haga clic en el botón siguiente para probar este endpoint en directo en su navegador.

Abrir consola

Address API - Autocompletado desde una sola línea (RESTful)

single

Solicitud

Ejemplos de cURL

Ejemplo de cURL

Parámetros

Respuesta

Nivel superior

Objeto de sugerencia de dirección - `Addresses[n]`

Ejemplo de respuesta

Errores

Probar la API

compl

Solicitud

Ejemplo de cURL

Ejemplo de cURL

Parámetros

Respuesta

Ejemplo de respuesta

Errores

Probar la API

Ver también

¿Fue útil este artículo?

Previous article

Next article

single

Solicitud

Ejemplos de cURL

Ejemplo de cURL

Parámetros

Respuesta

Nivel superior

Objeto de sugerencia de dirección - Addresses[n]

Ejemplo de respuesta

Errores

Probar la API

compl

Solicitud

Ejemplo de cURL

Ejemplo de cURL

Parámetros

Respuesta

Ejemplo de respuesta

Errores

Probar la API

Ver también

¿Fue útil este artículo?

Previous article

Next article

Objeto de sugerencia de dirección - `Addresses[n]`