Jugando con la API de Google Maps (II) – estructura JSON

Buenas,

Vimos en un mensaje anterior qué era y cómo obtener las coordenadas geográficas de una determinada dirección mediante la API de GeoCodificación de Google Maps. También vimos que la API podía devolver el resultado en dos formatos diferentes, JSON y XML. Me he decidido a explicar el JSON dado que es lo recomendado por Google. Para quien no sepa qué es el JSON, les recomiendo una visita a su web o en la wiki.

La estructura JSON

Cuando realizamos una búsqueda, ésta puede contener una dirección exacta de lo que buscamos (ej: Plaza de España, 5, Barcelona, España) o bien una parte de la misma (Ej: Plaza de España, 5). Como bien nos podemos imaginar, de «Plaza de España» hay muchas, por lo que la API de Google Maps nos devolverá todas las coincidencias que encuentre hasta un máximo de 10 (esta cantidad no la he visto reflejada en la documentación de Google Maps pero por las pruebas que he realizado parece que es así, no obstante, ésto no quiere decir que no salga dicha cantidad en la documentación).

Así pues, la estructura JSON devuelta por el API tendrá una parte común a todos los resultados (el estado de la consulta) y un array que contendrá todos los resultados.

Ésta sería una estructura base para 1 resultado de la llamada a la API:

{
  "status": "OK",
  "results": [ {
    "types": [ "street_address" ],
    "formatted_address": "Plaça d'Espanya, 5, 08014 Barcelona, Spain",
    "address_components": [ {
      "long_name": "5",
      "short_name": "5",
      "types": [ "street_number" ]
    }, {
      "long_name": "Plaça d'Espanya",
      "short_name": "Plaça d'Espanya",
      "types": [ "route" ]
    }, {
      "long_name": "Barcelona",
      "short_name": "Barcelona",
      "types": [ "locality", "political" ]
    }, {
      "long_name": "Barcelona",
      "short_name": "B",
      "types": [ "administrative_area_level_2", "political" ]
    }, {
      "long_name": "Catalonia",
      "short_name": "CT",
      "types": [ "administrative_area_level_1", "political" ]
    }, {
      "long_name": "Spain",
      "short_name": "ES",
      "types": [ "country", "political" ]
    }, {
      "long_name": "08014",
      "short_name": "08014",
      "types": [ "postal_code" ]
    } ],
    "geometry": {
      "location": {
        "lat": 41.3749536,
        "lng": 2.1485485
      },
      "location_type": "RANGE_INTERPOLATED",
      "viewport": {
        "southwest": {
          "lat": 41.3718069,
          "lng": 2.1454125
        },
        "northeast": {
          "lat": 41.3781022,
          "lng": 2.1517078
        }
      },
      "bounds": {
        "southwest": {
          "lat": 41.3749536,
          "lng": 2.1485485
        },
        "northeast": {
          "lat": 41.3749555,
          "lng": 2.1485718
        }
      }
    }
  } ]
}

Veamos cada una de las partes de este resultado:

• status: estado de la consulta. Hay varios estados, ver la API para consultarlos. A nosotros nos interesa el estado «OK» devuelto cuando la consulta se realiza correctamente y sin errores.
• results: array con los resultados devueltos por el API. Si no hay resultados a mostrar, devolverá un array vacío.
  • types: array con uno o más tags indicando el tipo de resultado. Ver en el API los diferentes tipos posibles.
  • formatted_address: dirección en formato «legible» devuelta por el API de Google Maps
  • address_components: array que contiene de forma desglosada el contenido de formatted_address. Éste suele tener la siguiente información:
    • types: array con el tipo de componente
    • long_name: todo el texto descriptivo del componente
    • short_name: abreviatura del componente si existiera.
  • geometry: lista con datos de localización
    • location: lista que contiene las coordenadas geográficas
      • lat: latitud
      • lng: longitud
    • location_type: información extra sobre la localización. Ver en el API los diferentes valores.
    • viewport: lista que contiene la ventana recomendada para la visualización del resultado.
      • southwest: lista con las coordenadas suroeste de la ventana.
        • lat: latitud
        • lng: longitud
      • northeast: lista con las coordenada noreste de la ventana.
        • lat: latitud
        • lng: longitud
    • bounds: (opcional) lista con la ventana que contiene la totalidad del resultado. Destacar que no tiene porque coincidir con el viewport.
      • southwest: lista con las coordenadas suroeste de la ventana.
        • lat: latitud
        • lng: longitud
      • northeast: lista con las coordenada noreste de la ventana.
        • lat: latitud
        • lng: longitud
  • partial_match: indica la exactitud del resultado devuelto. Aunque la documentación del API de Google Maps no lo marca como opcional, en las pruebas que he realizado no siempre ha devuelto este parámetro.

Continuará…

Nos leemos