Georreferenciando de manera fácil y simple con GeoNames utilizando C#/Mono

Introducción.

Últimamente he tenido ganas de desarrollar en C# para retomar este lenguaje que tengo un poco abandonado y al mismo tiempo probar los avances que ha tenido el proyecto Mono.  Que mejor inicio que desarrollar una aplicación muy simple para georreferenciar ciudades aprovechando el servicio web de Geonames, esta a su vez me servirá para complementarla y solucionar un problema de información que tengo para otro proyecto.

Como se podrá apreciar, el código es muy sencillo ya que no utilizo ninguna librería adicional a las estándar, sin embargo es interesante y puede serle de utilidad a alguien mas.

Cuál es la necesidad ?

El problema que se tiene es la necesidad de georreferenciar ubicaciones, es decir, conociendo su nombre obtener su ubicación en términos de latitud y longitud.

Si estoy en Manizales, Caldas, Colombia estaré realmente en latitud 5.07, longitud -75.52056.

Es necesario tener en cuenta que muchas veces el servicio de georreferenciación retorna múltiples resultados ya que pueden haberse referenciado varios sitios con el mismo nombre, haberse cambiado el nombre de la ubicación o tenerse varios hitos de diferente nivel administrativo.  En Geonames esto último se identifica mediante los campos de características.  Consulte el sitio web de Geonames para mas información acerca de los feature codes.

Cómo es el servicio web ?

El servicio web de búsquedas de Geonames recibe una cadena de texto con la ubicación que se desea georreferenciar y retorna una cadena de texto en formato XML (en este caso) con los resultados obtenidos.

Por ejemplo, la consulta de Manizales, Caldas, Colombia se realizaría a través del siguiente URL.

http://ws.geonames.org/search?lang=es&type=xml&style=FULL&q=Manizales,Caldas,Colombia

Retornará el siguiente resultado.

<geonames style="FULL">
    <totalResultsCount>2</totalResultsCount>
    <geoname>
        <toponymName>Manizales</toponymName>
        <name>Manizales</name>
        <lat>5.07</lat>
        <lng>-75.52056</lng>
        <geonameId>3675443</geonameId>
        <countryCode>CO</countryCode>
        <countryName>Colombia</countryName>
        <fcl>P</fcl>
        <fcode>PPLA</fcode>
        <fclName>city, village,...</fclName>
        <fcodeName>seat of a first-order administrative division</fcodeName>
        <population>357814</population>
        <alternateNames>Manisales,Manisalesas,Manizales,Манисалес</alternateNames>
        <elevation/>
        <continentCode>SA</continentCode>
        <adminCode1>37</adminCode1>
        <adminName1>Caldas</adminName1>
        <adminCode2/>
        <adminName2/>
        <alternateName lang="en">Manizales</alternateName>
        <alternateName lang="pl">Manizales</alternateName>
        <alternateName lang="lt">Manisalesas</alternateName>
        <alternateName lang="bg">Манисалес</alternateName>
        <alternateName lang="cs">Manizales</alternateName>
        <alternateName lang="link">http://en.wikipedia.org/wiki/Manizales</alternateName>
        <alternateName lang="de">Manizales</alternateName>
        <alternateName lang="sv">Manizales</alternateName>
        <alternateName lang="es">Manizales</alternateName>
        <alternateName lang="no">Manizales</alternateName>
        <alternateName lang="pt">Manizales</alternateName>
        <timezone dstOffset="-5.0" gmtOffset="-5.0">America/Bogota</timezone>
        <score>1.0</score>
    </geoname>
    <geoname>
        <toponymName>Manizales</toponymName>
        <name>Manizales</name>
        <lat>5.08333</lat>
        <lng>-75.5</lng>
        <geonameId>3675444</geonameId>
        <countryCode>CO</countryCode>
        <countryName>Colombia</countryName>
        <fcl>A</fcl>
        <fcode>ADM2</fcode>
        <fclName>country, state, region,...</fclName>
        <fcodeName>second-order administrative division</fcodeName>
        <population/>
        <alternateNames/>
        <elevation/>
        <continentCode>SA</continentCode>
        <adminCode1>37</adminCode1>
        <adminName1>Caldas</adminName1>
        <adminCode2>3675444</adminCode2>
        <adminName2>Manizales</adminName2>
        <timezone dstOffset="-5.0" gmtOffset="-5.0">America/Bogota</timezone>
        <score>0.3448537290096283</score>
    </geoname>
</geonames>

Finalmente la tarea de la aplicación que consuma el servicio será procesar el documento XML y obtener la información que necesite.

Cómo es la implementación ?

Las librerías (namespaces) utilizados son los siguientes.

using System;
using System.Net;
using System.Text;
using System.Xml;
using System.Collections.Generic;

Se prepara el URL para consumir el servicio con la ubicación a geocodificar.  En este caso, especifico una por defecto si no suministra una.

string location = (args.Length == 0) ? "Manizales, Caldas, Colombia" : args[0];
string url = "http://ws.geonames.org/search?lang=es&type=xml&style=FULL&q=" + location;

Se consume el servicio web y se obtiene la cadena de texto con la respuesta en formato XML.

WebClient client = new WebClient();
string xml = client.DownloadString(url);

Se crea un objeto para manipular el documento XML recién recibido, se obtienen los nodos relacionados con la respuesta de la georreferenciación (geoname)  y se verifica que haya registros, de lo contrario no habrá nada que hacer.

XmlDocument doc = new XmlDocument();
doc.LoadXml(xml);

XmlNodeList geonames = doc.GetElementsByTagName("geoname");

if(geonames.Count == 0)
 throw new Exception("There is no geonames in the result!");
else
 Console.WriteLine("I found " + geonames.Count + " places!n");

Se recorren los resultados obtenidos extrayéndoles la información georreferenciada que se requiera.

foreach(XmlElement place in geonames)
{
 Console.WriteLine("* LUGAR: " + place["name"].InnerText + "n");

 Console.WriteLine("tNombre: "          + place["name"].InnerText);
 Console.WriteLine("tDepartamento: "    + place["adminName1"].InnerText);
 Console.WriteLine("tLatitud: "         + place["lat"].InnerText);
 Console.WriteLine("tLongitud: "        + place["lng"].InnerText);
 Console.WriteLine("tPaís: "            + place["countryName"].InnerText +
                   " (" + place["countryCode"].InnerText + ")");
 Console.WriteLine("tPoblación: "       + place["population"].InnerText + " habitantes");
 Console.WriteLine("tPaís: "            + place["countryName"].InnerText +
                   " (" + place["countryCode"].InnerText + ")");
 Console.WriteLine("tCaracterísticas: " + place["fcl"].InnerText + "/" + place["fcode"].InnerText +
                   "> " + place["fclName"].InnerText + " (" + place["fcodeName"].InnerText + ")");

 Console.WriteLine();
}

Cómo construyo el programa ?

Si se utiliza VisualStudio/MonoDevelop sólo es necesario abrir la solución (incluída en el paquete de demostración) y ejecutar el comando de Build o Run del menú.

Si se desea realizar manualmente deberá ejecutarse un comando como el siguiente.

$ gmcs “/out:GeoCoderSimple.exe” “/r:/usr/lib/mono/2.0/System.dll” “/r:/usr/lib/mono/2.0/System.Xml.dll” /t:exe “geonames_search_raw/Main.cs

Donde geonames_search_raw/Main.cs es el código fuente de la aplicación y GeoCoderSimple.exe será el archivo binario resultante.

Cómo ejecuto el ejemplo ?

Ya sea invocándolo desde el IDE o desde línea de comando, el programa recibe un argumento.  En caso de obviarse este argumento se utilizará el valor por defecto.

$ ./GeoCoderSimple.exe

I found 2 places!

* LUGAR: Manizales

 Nombre: Manizales
 Departamento: Caldas
 Latitud: 5.07
 Longitud: -75.52056
 País: Colombia (CO)
 Población: 357814 habitantes
 País: Colombia (CO)
 Características: P/PPLA> city, village,... (seat of a first-order administrative division)

* LUGAR: Manizales

 Nombre: Manizales
 Departamento: Caldas
 Latitud: 5.08333
 Longitud: -75.5
 País: Colombia (CO)
 Población:  habitantes
 País: Colombia (CO)
 Características: A/ADM2> country, state, region,... (second-order administrative division)

Enlaces.

Demostración de georreferenciación al estilo web 2.0

La demostración de georreferenciación al estilo web 2.0 que permite visualizar el mapa de cualquier ubicación del mundo y ubicar sobre él marcadores georreferenciados.

Para esto utiliza los servicios de Google Maps para la generación de las imágenes y GeoNames para la georreferenciación, es decir, para convertir las ubicaciones (Manizales, Caldas, Colombia) en sus respectivas duplas latitud/longitud para poder ser relacionadas geográficamente.

En la parte izquierda se aprecia la lista con las ubicaciones seleccionadas que corresponden con las marcas rojas en el mapa, en la parte derecha está el mapa junto con tres barras de desplazamiento que regulan su presentación y en la parte inferior se encuentran los botones de opciones.

El demo le permite al usuario Agregar y Remover ubicaciones como puntos seleccionados.  Como se mencionó, estas se ingresan con los nombres de las ubicaciones y el sistema obtiene su ubicación geográfica a través de la consulta de un servicio web.  Es posible en cualquier momento, Centrar el mapa al rededor de cualquiera de los puntos seleccionados almacendos.

La manipulación del mapa se realiza con las barras de desplazamiento.  La naranja (derecha) corresponde con el zoom: hacia abajo aumenta, haciendo mayor el acercamiento del mapa.  La horizontal, azul, corresponde con la longitud y la vertical, verde, corresponde con la latitud.  Cuando se modifica cualquiera de estos valores se deberá solicitar la actualización del mapa presionando el botón Refrescar.

La aplicación ha sido desarrollada en Java por lo que su código es muy claro y modular.  En términos de la implementación, el acceso al webservice de GeoNames utiliza su propio API para el cual se descargaron dos archivos: geonames-1.0-java5.jar y jdom-1.0.jar.

La georrefernciación no podría ser más fácil.

    public static GeoLocation locate(String location) throws Exception
    {
        GeoLocation result = new GeoLocation();

        // Creates the toponym searcher

        ToponymSearchCriteria searchCriteria = new ToponymSearchCriteria();

        // Sets the criteria based on the specified location

        searchCriteria.setQ(location);

        // Request the geolocalization to the webserver

        ToponymSearchResult searchResult = WebService.search(searchCriteria);

        // Gets the results

        List toponyms = searchResult.getToponyms();

        // Checks if there were results

        if(toponyms == null || toponyms.size() == 0)
            return null;

        // Gets the first result of all (could be many)

        Toponym first = toponyms.get(0);

        // Prepares the result with its information

        result.put("geoNameId",   first.getGeoNameId()   + "");
        result.put("name",        first.getName()        + "");
        result.put("latitude",    first.getLatitude()    + "");
        result.put("longitude",   first.getLongitude()   + "");
        result.put("countryCode", first.getCountryCode() + "");
        result.put("countryName", first.getCountryName() + "");

        return result;
    }

La clase GeoLocation que utilizo para manejar el resultado no es mas que un Hashtable<String, String> con algunos adendos para facilitar su uso.

Por otro lado, la generación del mapa requiere aún menos ciencia aunque la realizo en dos pasos discretos que en general no incluyen nada extraño.

    public String prepareUrl()
    {
		String markers = "";

		// Walks thru all the points to create its markers

		for(int i=0; i

En el primer paso preparo el URL del consulta al servicio basado en información como la coordenada centro del mapa, el nivel de zoom, el tamaño de la imagen, los puntos seleccionados (marcadores) y la llave del API que debe ser privada y es única para cada sitio web (FQDN), aunque para el caso específico de aplicaciones de escritorio no es muy relevante a pesar de ser obligatoria.  La llave del API puede ser obtenida de manera gratuita por cualquier desarrollador desde esta dirección.

    public Image prepareImage(String url) throws Exception
    {
        Image image = ImageIO.read(new URL(url));

        return image;
    }

El segundo paso se relaciona con consultar el servicio de Google utilizando el URL recién generado, leer los bytes que conforman la imagen y crear con ellos un objeto Image para ser mostrado posteriormente en la interfaz de usuario.  Con Java, este procedimiento es extremadamente sencillo: 1 línea de código.

Para su uso se deberá tener cuidado en el manejo de las posibles excepciones que pueda lanzar el requerimiento como por ejemplo, producto de un fallo de red.

        // Gets the map image

        Image imageMap = mapService.getMap();

        // Checks if was received

        if(imageMap == null)
        {
            JOptionPane.showMessageDialog(this, "El mapa no se pudo recuperar.",
                    "Error recuperando mapa", JOptionPane.ERROR_MESSAGE);
            return;
        }

        // Puts the map on the gui

        map.setIcon(new ImageIcon(imageMap));

Teniendo el objeto Image lo podemos poner en cualquier componente de AWT/Swing.  Por facilidad, yo utilizo un JLabel que incluye el soporte de íconos (ImageIcon) los cuales se basan en objetos de imagen.

Como se puede apreciar, la complejidad de la aplicación es muy baja por lo que reitero: la imaginación es el límite.

Es posible acceder a la aplicación desde web sin instalar ningún archivo local desde el siguiente enlace o ejecutando el siguiente comando en una consola/símbolo del sistema operativo:

   $ javaws http://demo.jorgeivanmeza.com/Java/DemoGeoReferenceMap/0.1/DemoGeoReferenceMap.jnlp

Enlace: