Direcciones
Normalización de Direcciones
Descripción General
La normalización de una dirección postal consiste en el tratamiento de los datos postales validando la existencia de una dirección para un determinado alcance postal (localidad, provincia y/o CP), lo que permite identificar problemas de localidades, calles o alturas inexistentes o, formatos incompletos o incomprensibles de escritura. Por otro lado detecta distintas gramáticas de escritura de una dirección, permitiendo separar calle, número, piso, departamento y observaciones o comentarios informados. El resultado obtenido sera un domicilio validado y estandarizado en su escritura.
Además, a partir de la validación de existencia de la dirección, Merlin enriquece los datos postales faltantes : Código Postal, Barrio, Localidad, Partido y Provincia. La información se completa con la asignación de las entre calles correspondientes para brindar un localización más precisa.
Consideraciones generales
El cliente debe enviar una estructura de Dirección según lo detallado en el apartado «Datos de entrada» debiendo completar mínimamente los campos que se detallan a continuación:
- street: Este campo puede contener tanto el nombre de la calle como la dirección completa (street, houseNumber, floor, unit). Los campos houseNumber, floor, unit NO deben ser completados si se ingresa la calle completa en el campo “street”.
- level4: Corresponde al nivel de la localidad, puede no completarse si se informa el postalCode.
- level2: Corresponde al nivel de la provincia, puede no completarse si se informa el postalCode.
- postalCode: Corresponde al código postal, puede no completarse si se informa la level4.
- clientAccessCode: ID de acceso de cliente.
El resultado del proceso de normalización de una dirección sera la estructura de datos detallada en el apartado «Datos de salida»
Método: POST
Endpoint: https://ws.merlindataquality.com/address/ar/normalize
Datos de Entrada
| Atributo | Descripción | Longitud | Tipo |
| Authorization | Identificador único de usuarios. Este valor identifica y valida en cada invocación a un usuario determinado. Este valor tiene asociado los roles que le corresponden al usuario. | 64 | String |
| Content-Type | Header que se informa el tipo de contenido del mensaje, se debe informar application/json. | String | |
| street | Nombre de la calle o dirección completa. Puede incluir nombres de barrios cerrados, barrios zonales, rutas, alturas, piso, depto, referencias, nombres de puntos de interés, etc. | 64 | String |
| houseNumber | Número de la dirección. | 10 | String |
| floor | Piso de la dirección. | 2 | String |
| unit | Departamento, número de casa, oficina, PH, local, entre otros elementos de la dirección. | 3 | String |
| additionalData | Observaciones o datos adicionales de la calle. | 64 | String |
| customAdapterKeys |
Adaptadores de respuesta/modificadores de comportamiento. Valores:
|
– | Array |
| postalCode | Código Postal de la dirección. | 4 | String |
| level1 | Corresponde al primer nivel (País) administrativo de una dirección. <<Niveles Administrativos>> | 64 | String |
| level2 | Corresponde al segundo nivel administrativo de una dirección. Por ejemplo para Argentina, corresponde a Provincia. <<Niveles Administrativos>> | 64 | String |
| level3 | Corresponde al tercer nivel administrativo de una dirección. Por ejemplo para Argentina, corresponde al Partido. <<Niveles Administrativos>> | 64 | String |
| level4 | Corresponde al cuarto nivel administrativo de una dirección. Por ejemplo para Argentina, corresponde a Localidad.<<Niveles Administrativos>> | 64 | String |
| level5 |
Corresponde al quinto nivel administrativo de una dirección. Por ejemplo para Argentina, corresponde a Barrio. <<Niveles Administrativos>> |
64 | String |
Nota:
Para la normalización de Rutas utilizar el token «Ruta» e informar si es Nacional o Provincial más el kilometraje con el prefijo Km.
- Ejemplo: Ruta Nacional 12 Km 1575
- Ejemplo: Ruta Provincial 2 Km 34
En los casos de Barrios utilizar los token «Barrio» , «BO» o «Country».
- Ejemplo: Bo Club de Campo El Paso, San Tome, Santa Fe
- Ejemplo: Barrio Club de Campo El Paso, CP 3016
- Ejemplo: Country Club de Campo El Paso, Santa Fe, CP 3016
Mensaje JSON 2.5 de petición
{
"street": "San Martin 500",
"houseNumber": "",
"floor":"2",
"unit": "D",
"additionalData":"casa azul",
"customAdapterKeys": [],
"postalCode": "1004",
"level1": "AR",
"level2": "",
"level3": "",
"level4": "",
"level5": ""
}Datos de Salida
| Atributo | Descripción | Longitud |
Tipo |
| status | Indica el estado de normalización y/o validación. Para mas información ver el apartado «Estados y Motivos». | 3 | String |
| statusReason | Indica la razón con referencia al estado de normalización y/o validación. Para mas información ver el apartado«Estados y Motivos». | 2 | String |
| transactionId | Merlin asigna un id de transacción por consulta. | 10 | String |
| nAddress | Son los datos de la dirección ya corregida. Si la dirección no pudo ser corregida, aquí se encontrarán los datos de la dirección original parseados de haber sido posible. | – | String |
| street | Nombre de la calle normalizada o estandarizada. | 64 | String |
| houseNumber | Numeración de la dirección. | 10 | String |
| floor | Piso de la dirección. | 2 | String |
| unit | Departamento, numero de casa, oficina, PH, local, entre otros elementos de la dirección. | 6 | String |
| postalCode | Código postal de la dirección. | 4 | String |
| additionalPostalCode | Codigo postal adicional. Por ejemplo para Argentina, «Código Postal Argentino» (CPA). | 8 | String |
| level1 | Corresponde al primer nivel (País) administrativo de una dirección. Para más información ver «Niveles administrativos». | 64 | String |
| level2 | Corresponde al segundo nivel administrativo de una dirección. Por ejemplo para Argentina, corresponde a Provincia. Para más información ver «Niveles administrativos». | 64 | String |
| level3 | Corresponde al tercer nivel administrativo de una dirección. Por ejemplo para Argentina, corresponde a Partido. Para más información ver«Niveles administrativos». | 64 | String |
| level4 | Corresponde al cuarto nivel administrativo de una dirección. Por ejemplo para Argentina, corresponde a Localidad. Para más información ver«Niveles administrativos». | 64 | String |
| level5 | Corresponde al quinto nivel administrativo de una dirección. Por ejemplo para Argentina, corresponde a Barrio. Para más información ver«Niveles administrativos». | 64 | String |
| fromStreetNumber | Altura inicial para la calle normalizada. | 10 | String |
| toStreetNumber | Altura final para la calle normalizada. | 10 | String |
| betweenStreet1 | Primera transversal del domicilio. | 64 | String |
| betweenStreet2 | Segunda transversal del domicilio. | 64 | String |
| placeType | Tipo de punto de interés, lugar, etc. | 12 | String |
| place | Nombre del punto de interés, lugar, etc. | 64 | String |
| corner | Esquina de la dirección o denominación de la esquina a normalizar. | 64 | String |
| streetType | Tipo de vialidad como ser avenida, calle,etc. | 12 | String |
| placeReference | Datos complementarios de como llegar al domicilio normalizado, es utilizado para los barrios cerrados. Para màs información ver «Resolución de POIS» | 64 | String |
| additionalData | Son datos extras encontrados en la dirección original que no corresponden a ningún campo. | 64 | String |
| idSegment | Informa el número del segmento si está relevado | 64 | String |
| geoType | Tipo de georeferenciación, ver documento «Tipo de Geocodificación». | 2 | |
| latitude | Coordenada Y de georeferenciación. | 10 | String |
| longitude | Coordenada X de georeferenciación. | 10 | String |
| merlinCustomValues | Valores desarrollados por Merlín para todos los clientes. Ver más sobre <<Customs Adapters>> | — | ArrY |
| clientCustomValues | Valores desarrollados por demanda del cliente o que se provee opcionalmente. Ver más sobre <<Customs Client Adapters>> | – | Array |
| alternativeAddresses | Si existe mas de una a la dirección posible para los datos ingresados, aquí se retornará N estructuras de respuesta de direcciones. El máximo posible de direcciones dudosas es de 5. Es decir, que es posible que la estructura se repita de 1 a 5 veces. Si no existieron direcciones alternativas, entonces el campo estará vacío. | – | Array |
| numberAlternativeAddresses | Cantidad de direcciones alternativas. | 1 | String |
Mensaje JSON de respuesta
{
"status": "CO",
"statusReason": "SM",
"transactionId": "0792bc2c-bb5c-4333-8a8b-6168b6b73312",
"nAddress": {
"street": "SAN MARTIN",
"houseNumber": "500",
"floor": "2",
"unit": "D",
"postalCode": "1004",
"additionalPostalCode": "C1004AAJ",
"level1": "AR",
"level2": "CAPITAL FEDERAL",
"level3": "CAPITAL FEDERAL",
"level4": "CIUDAD AUTONOMA BUENOS AIRES",
"level5": "SAN NICOLAS",
"fromStreetNumber": "1",
"toStreetNumber": "1400",
"betweenStreet1": "AVDA CORRIENTES",
"betweenStreet2": "GRAL JUAN LAVALLE",
"place": "",
"placeType": "",
"corner": "",
"streetType": "",
"placeReference": "",
"additionalData": "",
"idSegment": "10331194",
"geoType": "1",
"longitude": "-58.373966",
"latitude": "-34.602308",
"merlinCustomValues": {
"postalCertifiedAddresses": "SI",
"level4Longitude": "-58.446264",
"level4Latitude": "-34.614420",
"nise": "8",
"merlinRiskArea": "N"
},
"clientCustomValues": {},
"alternativeAddresses": [],
"numberAlternativeAddresses": "0"
}
}