USIGNormalizador

Cliente iOS del servicio de normalización de direcciones de USIG para CABA y AMBA, desarrollado en Swift 4.

Instalación

Cocoapods

En el Podfile del proyecto:

pod 'USIGNormalizador', '~> 2.0'

Carthage

En el Cartfile del proyecto:

github "gcba/usig-normalizador-ios" ~> 2.0

Métodos

Búsqueda por calle

Devuelve un array de direcciones ordenadas por relevancia de acuerdo al término de búsqueda.

USIGNormalizador.search(query: <Nombre o parte del nombre de una calle>) { result, error in
    // Do something
}

Parámetros opcionales

excluding (String?)

Localidades a excluir de la búsqueda, separadas por coma. Por defecto se excluyen todas las localidades del AMBA (para obtener resultados sólo de CABA).

USIGNormalizador.search(query: "Callao", excluding: nil) { result, error in
    // Do something
}

maxResults (Int)

Cantidad máxima de resultados a devolver. Por defecto son 10.

USIGNormalizador.search(query: "Callao", maxResults: 7) { result, error in
    // Do something
}

includePlaces (Bool)

Incluir lugares en la búsqueda o no. Por defecto es true.

USIGNormalizador.search(query: "Callao", includePlaces: false) { result, error in
    // Do something
}

Los parámetros opcionales pueden ir juntos o separados.

USIGNormalizador.search(query: "Callao", excluding: nil, maxResults: 7, includePlaces: false) { result, error in
    // Do something
}

Búsqueda por coordenadas

Devuelve la dirección más próxima a una latitud/longitud.

USIGNormalizador.location(latitude: <Una latitud>, longitude: <Una longitud>) { result, error in
    // Do something
}

Interfaz

Permite buscar por el nombre de una calle o lugar. El controlador de la interfaz de búsqueda debe ser presentado por un UINavigationController.

let searchController = USIGNormalizador.searchController()
let navigationController = UINavigationController(rootViewController: searchController)

searchController.delegate = self

present(navigationController, animated: true)

Editar

Es posible precargar un término de búsqueda antes de presentar el controlador.

searchController.edit = "CALLAO AV. 123"

Modalidades

Hay dos modalidades opcionales, que pueden activarse juntas o separadas:

Mostrar pin

Agrega una celda en la parte superior de la tabla con la imagen de un pin y un texto configurable. Cuando se la tapea ejecuta el método didSelectPin del delegado. Se activa implementando el método shouldShowPin del delegado para que retorne true.

No forzar normalización

Da la posibilidad al usuario de escribir y elegir una calle que no esté entre los resultados de la búsqueda. Muestra una celda arriba de los resultados con el término de búsqueda ingresado, y cuando se la tapea pasa este valor al método didSelectUnnormalizedAddress. Se activa cuando el método shouldForceNormalization del delegado retorna false.

Delegado

El controlador de búsqueda se configura implementando métodos del protocolo USIGNormalizadorControllerDelegate. Es obligatorio implementar didSelectValue; los demás métodos son opcionales.

shouldShowPin

Si se muestra la celda con el pin. El valor por defecto es false.

func shouldShowPin(_ searchController: USIGNormalizadorController) -> Bool {
    return true
}

shouldForceNormalization

Si se fuerza la normalización de las direcciones. El valor por defecto es true.

func shouldForceNormalization(_ searchController: USIGNormalizadorController) -> Bool {
    return false
}

shouldIncludePlaces

Si se incluyen lugares en la búsqueda. El valor por defecto es true.

func shouldIncludePlaces(_ searchController: USIGNormalizadorController) -> Bool {
    return false
}

shouldShowDetails

Si se muestran el partido y la localidad de cada dirección. El valor por defecto es false.

func shouldShowDetails(_ searchController: USIGNormalizadorController) -> Bool {
    return true
}

didSelectValue

Se ejecuta al tapear en uno de los resultados de la búsqueda.

func didSelectValue(_ searchController: USIGNormalizadorController, value: USIGNormalizadorAddress) {
    // Do something
}

didSelectUnnormalizedAddress

Cuando se selecciona la dirección custom escrita por el usuario.

func didSelectUnnormalizedAddress(_ searchController: USIGNormalizadorController, value: String) {
    // Do something
}

didSelectPin

Se ejecuta al tapear la celda del pin.

func didSelectPin(_ searchController: USIGNormalizadorController) {
    // Do something
}

didCancelSelection

Si se tapeó el botón Cancelar.

func didCancelSelection(_ searchController: USIGNormalizadorController) {
    // Do something
}

exclude

Localidades a excluir de la búsqueda, separadas por coma. El valor por defecto son las localidades del AMBA (para obtener resultados sólo de CABA).

func exclude(_ searchController: USIGNormalizadorController) -> String {
    return nil
}

maxResults

Cantidad máxima de resultados a devolver. Por defecto es 10.

func maxResults(_ searchController: USIGNormalizadorController) -> Int {
    return 7
}

pinImage

Permite cambiar el ícono del pin.

func pinImage(_ searchController: USIGNormalizadorController) -> UIImage! {
    return UIImage(named: "MyIcon")
}

pinColor

Color de tint que se aplicará al ícono del pin. El color por defecto es UIColor.lightGray.

func pinColor(_ searchController: USIGNormalizadorController) -> UIColor {
    return UIColor.black
}

pinText

El texto que aparecerá junto al pin. Por defecto es "Fijar la ubicación en el mapa".

func pinText(_ searchController: USIGNormalizadorController) -> String {
    return "Marcar en el mapa"
}

addressImage

Permite cambiar el ícono de las direcciones.

func addressImage(_ searchController: USIGNormalizadorController) -> UIImage! {
    return UIImage(named: "MyIcon")
}

addressColor

Color de tint que se aplicará al ícono de las direcciones. El color por defecto es UIColor.lightGray.

func addressColor(_ searchController: USIGNormalizadorController) -> UIColor {
    return UIColor.black
}

placeImage

Permite cambiar el ícono de los lugares.

func placeImage(_ searchController: USIGNormalizadorController) -> UIImage! {
    return UIImage(named: "MyIcon")
}

placeColor

Color de tint que se aplicará al ícono de los lugares. El color por defecto es UIColor.lightGray.

func placeColor(_ searchController: USIGNormalizadorController) -> UIColor {
    return UIColor.black
}

Localización

Para que el botón Cancelar aparezca en español, asegurarse que en el Info.plist de la app la clave Localization native development region tenga el valor es.

API

USIGNormalizador.api expone un Moya provider para realizar llamadas directas al servicio de normalización de direcciones de USIG.

Licencia

MIT License

Copyright (c) 2017+ Buenos Aires City Government

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.