# Place Autocomplete

El servicio Place Autocomplete es un servicio web que devuelve predicciones de lugares en respuesta a una solicitud HTTP. La solicitud especifica una cadena de búsqueda textual y límites geográficos opcionales. El servicio se puede utilizar para proporcionar la funcionalidad de autocompletar para búsquedas geográficas basadas en texto, al devolver lugares como negocios, direcciones y puntos de interés a medida que el usuario escribe.

# Solicitudes de Place Autocomplete

El servicio Place Autocomplete puede hacer coincidir palabras completas y subcadenas, resolviendo nombres de lugares y direcciones. Por lo tanto, las aplicaciones pueden enviar consultas a medida que el usuario escribe, para proporcionar predicciones de lugares sobre la marcha.

Las predicciones devueltas están diseñadas para ser presentadas al usuario para ayudarlo a seleccionar el lugar deseado. Puede enviar una Solicitud de Place Fields para obtener más información sobre cualquiera de los lugares que se devuelven.

Una solicitud de Place Autocomplete es una URL HTTP con el siguiente formato:

https://apis.geodir.co/places/autocomplete/v1/**outputFormat**?**parameters**

donde outputFormat puede ser cualquiera de los siguientes valores:

json (recomendado) indica la salida en Notación de Objetos JavaScript (JSON); o
xml indica salida en XML

La seguridad es importante y se recomienda HTTPS siempre que sea posible, especialmente para aplicaciones que incluyen datos confidenciales del usuario, como la ubicación de un usuario, en las solicitudes. El uso de la encriptación HTTPS hace que su aplicación sea más segura y más resistente a espionaje o manipulación.

Nota: las URL deben estar codificadas correctamente (consulte Mejores Prácticas) para válidos y están limitados a 8000 caracteres para todos los servicios web. Tenga en cuenta este límite al crear sus URL. Tenga en cuenta que los diferentes navegadores, proxies y servidores también pueden tener diferentes límites de caracteres de URL.

Algunos parámetros son obligatorios mientras que otros son opcionales. Como es estándar en las URL, los parámetros se separan mediante el carácter comercial (&).

Parámetros obligatorios en una solicitud de Place Autocomplete:

key: la clave API de su aplicación. Esta clave identifica su aplicación a los efectos de la gestión de cuotas. Obtén información sobre cómo Obtener tu clave de API.
search: la cadena de texto en la que buscar. El servicio Place Autocomplete devolverá las coincidencias candidatas en función de esta cadena y ordenará los resultados según su relevancia percibida.

Ejemplos de solicitudes de Place Autocomplete

Una solicitud para establecimientos que contengan la cadena "Rebagliati" dentro de un área con centro en Lima, PE:

https://apis.geodir.co/places/autocomplete/v1/json?text=Rebagliati&types=establishment&key=YOUR_KEY

# Respuestas de Place Autocomplete

Las respuestas de Place Autocomplete se devuelven en el formato indicado por la marca de salida dentro de la ruta de la URL de la solicitud. Los resultados a continuación son indicativos de lo que se puede devolver para una consulta con los siguientes parámetros:

search=jiron pedro ruiz gallo 658

{
    "status": "OK",
    "predictions": [
        {
            "types": [
                "route_number",
                " geocode"
            ],
            "description": "Jiron Pedro Ruiz Gallo 658, Breña, Lima, Perú",
            "main_text": "Jiron Pedro Ruiz Gallo 658",
            "secondary_text": "Breña, Lima, Perú",
            "place_id": "NGU2Mzg0YWYtMjkwMS01NGRjLTg1MWYtODQ1MGU2OWZhMzU4"
        },
        {
            "types": [
                "route_number",
                " geocode"
            ],
            "description": "Jirón Comandante Pedro Ruiz Gallo 658, Callao, Callao, ",
            "main_text": "Jirón Comandante Pedro Ruiz Gallo 658",
            "secondary_text": "Callao, Callao, ",
            "place_id": "NGU2Mzg0YWYtMjkwMS01NGRjLTg1MWYtODQ1MGU2OWZhMzU4"
        }
    ]
}

Una respuesta JSON contiene hasta dos elementos raíz:

status contiene metadatos sobre la solicitud. Consulte Códigos de Estado.
predictions contiene una variedad de lugares, con información sobre el lugar. Consulte resultados de Place Autocomplete para obtener información sobre estos resultados. La API de Places devuelve hasta 5 resultados.

De particular interés dentro de los resultados son los elementos place_id, que se pueden usar para solicitar detalles más específicos sobre el lugar a través de una consulta separada. Consulte Solicitudes de Place Fields.

Consulte Procesando JSON con JavaScript para obtener ayuda sobre cómo analizar las respuestas JSON.

Una respuesta XML consta de un único elemento PlaceAutocompleteResponse con dos tipos de elementos secundarios:

Un único elemento status contiene metadatos sobre la solicitud. Consulte Códigos de Estado.
Cero o más elementos de prediction, cada uno de los cuales contiene información sobre un solo lugar. Consulte Resultados de Place Autocomplete para obtener información sobre estos resultados. La API de Places devuelve hasta 5 resultados.

Le recomendamos que utilice json como marca de salida preferida a menos que su aplicación requiera xml por alguna razón. El procesamiento de árboles XML requiere cierto cuidado, de modo que haga referencia a los nodos y elementos adecuados. Consulte Procesando XML con XPath para obtener ayuda sobre el procesamiento de XML.

# Códigos de Estado

El campo "status" dentro del objeto de respuesta Place Autocomplete contiene el estado de la solicitud y puede contener información de depuración para ayudarlo a rastrear por qué falló la solicitud Place Autocomplete. El campo "status" puede contener los siguientes valores:

"OK" indica que no se produjeron errores y se devolvió al menos uno de los resultados.
"ZERO_RESULTS" indica que la búsqueda fue exitosa pero no arrojó resultados. Esto puede ocurrir si la búsqueda pasó un límite en una ubicación remota.
"OVER_QUERY_LIMIT" indica que ha superado su cuota.
"REQUEST_DENIED" indica que su solicitud fue denegada, generalmente debido a la falta de un parámetro clave válido.
"INVALID_REQUEST" generalmente indica que falta el parámetro de texto.
"UNKNOWN_ERROR" indica un error del lado del servidor; intentarlo de nuevo puede tener éxito.

# Mensajes de Error

Cuando el servicio de Places devuelve un código de estado que no es OK, puede haber un campo message adicional dentro del objeto de respuesta. Este campo contiene información más detallada sobre las razones detrás del código de estado dado.

# Resultados de Place Autocomplete

Cuando el servicio Places devuelve resultados JSON de una búsqueda, los coloca dentro de una matriz de predictions. Incluso si el servicio no devuelve resultados (por ejemplo, si location es remoto), todavía devuelve una matriz de predictions vacía. Las respuestas XML constan de cero o más elementos de prediction.

Cada resultado de predicción contiene los siguientes campos:

description contiene el nombre legible por humanos del resultado devuelto. Para los resultados de establishment, este suele ser el nombre de la empresa.
place_id es un identificador textual que identifica un lugar de forma única. Para recuperar información sobre el lugar, transfiera este identificador en el campo place_id de una solicitud de la API de Places. Para obtener más información sobre los ID de lugar, consulte ID de Place.
types contiene una variedad de tipos que se aplican a este lugar. Por ejemplo: [ "political", "locality" ] o [ "establishment", "geocode", "beauty_salon" ]. La matriz puede contener varios valores. Más información sobre Tipos de Places.
main_text contiene el texto principal de una predicción, generalmente el nombre del lugar.
secondary_text contiene el texto secundario de una predicción, generalmente la ubicación del lugar.

← Place Fields Lista de Campos →