Cómo crear un Mashup combinando 3 API diferentes

() translation by (you can also view the original English article)

Este tutorial le mostrará cómo crear un mashup de tres API diferentes, incluida la integración con Google Maps. Esta idea surgió cuando buscaba en el directorio de la API de ProgrammableWeb un par de API que se complementaban lo suficiente como para poder usar una para proporcionarle a la otra información. Lo que se me ocurrió será conocido como "Beer Mashup".

Paso 1. API Discovery

Mientras miraba el directorio de ProgrammableWeb, encontré una herramienta de geolocalización de IP llamada ipLoc. Simplemente acepta en una dirección IP y devuelve datos relevantes específicos de la ubicación, como su estado, ciudad, país, código postal, etc.

Luego encontré el genial Beer Mapping Project, que tiene un gran directorio de bares y pubs no solo de EE. UU., Sino de muchos otros países. Al instante me di cuenta de que este era un complemento perfecto para ipLoc porque la API BeerMapping requiere una ciudad (que podemos obtener de la API de ipLoc) para devolver una lista de bares y pubs locales.

Por último, también quería integrar Google Maps en este mashup para trazar las direcciones de las barras y las publicaciones para agregar un poco de interactividad a la página en lugar de mostrar cada barra en una simple lista de HTML.

Paso 2. Inicialización de variables

Por lo general, lo mejor es iniciar documentos PHP con algunas de las variables que quiero configurar globalmente dentro del script. Aquí agrego una línea que silencia los mensajes de advertencia de PHP (Google Maps escupe muchos de estos si intentas asignar una dirección no válida) y mis claves de BeerMashup y API de Google Maps. Terminaremos usando estas claves de API cuando lleguemos a sus respectivos pasos a continuación.

<?php
  error_reporting(E_ERROR|E_PARSE);  //Silence Errors
	
//Initialize Variables
	$beer_api = 'YOUR_BEERMAPPING_API_KEY';
	$gmaps_api = 'YOUR_GOOGLEMAPS_API_KEY';

Paso 3. Configuración de la geolocalización de IP

La API de ipLoc le permite especificar una dirección IP para obtener datos o usar la dirección IP predeterminada que encuentra el script.

Versión predeterminada: http://iploc.mwudka.com/iploc/json/
Versión estática (la dirección IP está codificada): http://iploc.mwudka.com/iploc/68.162.155.110/json/

//Set Location
	//Visitor IP Address
	$ip = getenv("REMOTE_ADDR");
	
	//via IPLoc
	$iploc = file_get_contents("http://iploc.mwudka.com/iploc/$ip/json/");  //Format: JSON
	$ipdata = json_decode($iploc, true);

Después de algunas pruebas, me di cuenta de que la versión predeterminada de la API ipLoc era encontrar la ubicación (Scottsdale, AZ, EE. UU.) Del servidor de mi proveedor de alojamiento en lugar de la ubicación IP de la computadora de mi casa (Pittsburgh, PA, EE. UU.). Para evitar esto, decidí usar la versión de IP estática de la API (Línea 2 arriba) y pasé la dirección IP que es detectada por la variable php getenv ("REMOTE_ADDR").

Después de verificar si los datos se han devuelto con éxito como una cadena con formato json descodificada, debemos extraer solo los datos específicos que queremos transferir a la API de BeerMapping, que es la ciudad y el estado.

	// Error checking
	if ($ipdata['city']) { 
		$city = $ipdata['city'];
		$state = $ipdata['region'];
		$location = $city .", ". $state;
	} else {
		$err = "No location data returned for your IP address: ". $ip; 

	}

Paso 4. Integración de Google Maps

Este paso debe hacerse ahora porque el próximo paso agregará los puntos de ubicación a Google Maps, y Google Maps debe iniciarse antes de que eso ocurra.

Para hacer que la integración de Google Maps sea lo más fácil y sencilla posible, he solicitado la ayuda de una excelente clase de PHP llamada Phoogle de System Seven Designs. Esta clase se encarga de todo el trabajo pesado de la API de Google Maps y nos permite preocuparnos por los datos.

Todo lo que debemos hacer para que esto funcione es primero incluir el archivo de clase que descargamos: phoogle.php, luego establecer algunos parámetros básicos del mapa, como la altura, el ancho, el nivel de zoom y su clave API de Google Maps. (Consigue uno de esos aquí).

//Phoogle - GoogleMaps PHP Class
	require_once 'phoogle.php';
	$map = new PhoogleMap();
	$map->setAPIKey($gmaps_api); //Using the variable we set in Step 2
	$map->setHeight(450);
	$map->setWidth(750);
	$map->zoomLevel = 6;
	$map->showType = false;

Paso 5. BeerMapping API

Como tenemos la ciudad y el estado combinados en la $location de la variable del Paso 3, tenemos todo lo que necesitamos para extraer datos de la API de BeerMapping. Por supuesto, también necesitamos una de sus claves API, que puede solicitarse aquí (alrededor de un proceso de 30 segundos, de principio a fin).

Una llamada a la API BeerMapping se parece a esto de acuerdo con sus ejemplos:
Ejemplo real: http://beermapping.com/webservice/loccity/71515667a86b8ec7f58cd22e3af86f6e/pittsburgh,pa

Después de sustituir nuestras variables por la Clave de API (Paso 2) y la Ubicación (Paso 3), nuestra llamada a la API BeerMapping ahora se ve así:
Nuestro ejemplo: http://beermapping.com/webservice/loccity/$beer_api/$location

Después de jugar un poco con esta API, encontré que la ubicación no puede tener ningún espacio. Por lo tanto, el código a continuación primero elimina el espacio entre el formato "ciudad, estado". Luego reemplaza todos los demás espacios dentro de la ubicación con guiones bajos "_".

//Format Location for use with API

	$locationF = str_replace(", ", ",", $location); // Remove space before "State"

	$locationF = str_replace(" ", "_", $locationF); // Replace space with underscore in "City" name

Sus datos solo pueden devolverse en formato xml, por lo que podemos extraer fácilmente los datos devueltos por esta llamada con la función simplexml_load_file PHP.

1	//BeerMapping - Format: XML
2	$beerdata = simplexml_load_file ("http://beermapping.com/webservice/loccity/$beer_api/$locationF");

Como muestra la imagen, primero cargamos el archivo completo en la variable $ beerdata. Después de comprobar si hemos devuelto algún resultado ...

	// Error checking
	$beererr = $beerdata->location->id; //$beererr will be 0 if there were no locations returned
	if ($beererr == '0') { 
		$err = "No breweries were found in ". $location; 
	} else {

... el siguiente paso es recorrer cada barra / pub devuelto en la llamada, extrayendo todos los datos que necesitamos para pasar a Google Maps (Paso 4).

		$breweries = $beerdata->location;
		$barcount = count($breweries); //How Many?
		
		foreach ($breweries as $brewery) {
			$name = $brewery->name;
			$link = $brewery->reviewlink;
			$street = $brewery->street;
			$city = $brewery->city;
			$state = $brewery->state;
			$zip = $brewery->zip;
			$phone = $brewery->phone;
			
			//Location Point set for the Google Maps API
			$map->addAddress("$street $city $state $zip", "<a href='$link' title='$name BeerMap'>$name</a><br/>$street<br />$city, $state $zip<br />Phone: $phone");
		} 
	}
?>

La línea 1 anterior establece la ubicación de la estructura de las "ubicaciones". La línea 2 cuenta la cantidad de "ubicaciones" que devolvió el resultado de la API. Las líneas restantes usan un bucle foreach para recorrer cada "ubicación" y extraer la información de la dirección. La línea 14 establece un "punto" para cada cervecería en nuestro mapa de Google.

Paso 6. Generación de HTML

Después de terminar todo el código PHP que hemos creado, ahora podemos trabajar en mostrarlo. Las primeras líneas que se muestran a continuación son estándar en cualquier documento HTML, pero después de eso volvemos a usar PHP. Primero verificamos si la variable $ err es FALSE, lo que significa que la variable $ err está vacía o que nunca recibimos un error. Si nunca recibimos un error, escupimos el mapa de Google, de lo contrario, escupimos un mensaje de error.

<html xmlns="http://www.w3.org/1999/xhtml">
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<link rel="stylesheet" type="text/css" href="styles.css" />
<title>Bars Near <?php echo $location; ?></title>
</head>
	<body>
	<div class="wrapper">
		<div class="header">
			<img class="logo" src="images/logo.png" alt="The Beer Mashup" />
			
			<p class="footer">Developed by <a href="http://www.cagintranet.com">Chris Cagle</a> for <a href="http://www.nettuts.com">NETTUTS</a></p>
			
			<div class="mapdiv">
				<?php 
				if (!$err) {
					echo "<div>";
					$map->printGoogleJS();
					$map->showMap();
					echo "<h3>". $location ." <span>(". $barcount ." Bars)</span></h3>";
				} else {
					echo "<p class=\"error\"><b>". $err ."</b></p>";;
				} 
				?>
			</div>
		</div>	
	</div>	
	</body>
</html>

Después de agregar un poco de texto y CSS, ahora tiene una excelente página web que muestra todos los bares y pubs cerca de la ubicación de quien está viendo la página web.

Ver la demostración de la página tal como está ahora. El mashup está funcionando muy bien ahora, pero tenemos una mejora más que hará toda la diferencia cuando se trata de UI.

Paso 7. Cambiar el código para permitir que el visitante ingrese las ubicaciones

En este punto, nuestra página funciona bien pero hay una pequeña advertencia: el visitante solo puede ver las barras desde su ubicación actual. ¿Qué sucede si el visitante desea barras de búsqueda en una ciudad diferente en lugar de la que le devolvió nuestra API de IP? Cualquier visitante querría la posibilidad de especificar la ubicación para investigar.

Para permitir esto, tendremos un formulario simple que se aceptará en una ciudad y estado del visitante, luego se volverá a cargar la página para la ubicación dada y se omitirá la llamada a la API ipLoc por completo. Insertaremos este código justo antes de nuestra línea en el Paso 6.

<form method="post" id="form" action="beermashup2.php">
	<span>location: (ex. New Orleans, LA)</span>
	<input type="text" value="" name="loc" id="loc" /><br class="clear" />
	<input type="submit" id="submitted" value="SEARCH" name="submitted" />
</form>

Para que esto funcione, tendremos que envolver el código que hicimos en el paso ipLoc (Paso 3) en una declaración if que compruebe si el formulario se envió o no. Si el formulario * no fue * enviado (lo que sucederá cada vez que la página se cargue inicialmente), entonces usará el código de geolocalización IP ipLoc. Si el formulario * fue * enviado, tomará lo que el usuario envió y establecerá nuestra variable $ location.

//Set Location
	if ( isset($_POST['loc']) ) {
		//via user input
		$location = $_POST['loc']; 
	} else {
		//Visitor IP Address
		$ip = getenv("REMOTE_ADDR");

		//via IPLoc
		$iploc = file_get_contents("http://iploc.mwudka.com/iploc/$ip/json/");  //Format: JSON
		$ipdata = json_decode($iploc, true);
		
		// Error checking
		if ($ipdata['city']) { 
			$city = $ipdata['city'];
			$state = $ipdata['region'];
			$location = $city .", ". $state;
		} else {
			$err = "No location data returned for your IP address: ". $ip; 
		}

Paso 8. Poniendo todo junto

Ver la demo de la aplicación final.

Puede ver el código fuente del proyecto final (que es más o menos los pasos anteriores juntos) y ver cómo terminé combinando 3 API separadas en una aplicación. Dé un paseo por usted mismo a través del directorio de API en ProgrammableWeb y vea lo que puede hacer por su cuenta. Trabajar con API es mi nueva obsesión porque es emocionante poder crear algo nuevo y útil a partir de los datos de otra persona. Si este tutorial te ha ayudado a combinar un par de API, publícalos aquí. Me encantaría verlas.