Yahoo Placefinder-API Tutorial

Habe mich gestern auf Arbeit für eine Geo-Location Klasse mit der Placefinder API auseinandergesetzt und war ganz angetan davon, deswegen gebe hier mal die „Essentials“ wieder.

Was kann Placefinder?

Placefinder hat 2 Haupt-Einsatzbereiche:

• Finde die Lat/Long-Koordinaten einer eingegebenen Adresse (Bspw: Neckarstraße 15, Darmstadt -> 49.869220, 8.645537)
• Finde zu angegebenen Lat/Long-Koordinaten die nächstgelegene Adresse (Bspw: 48.1431,8.4176 -> Am Doniswald 8, 78126 Königsfeld Im Schwarzwald)

Dabei ist der Placefinder sehr „tolerant“, spuckt also auch zu mies formatierten Eingaben oder Tippfehlern korrekte Ergebnisse aus.

Wie spreche ich die API an?

Yahoo bittet euch, erstmal einen API-Key zu besorgen (das geht hier). Komischerweise hat Yahoo aber auch nichts dagegen, wenn bei Anfragen kein API-Key angegeben wird – aber sicher ist sicher. Danach gibt es grundlegend 3 relevante Verfahren, die API anzusprechen:

Koordinaten einer Adresse finden

1) Simples „one string“-Format:

$location = "Neckarstraße 15, Darmstadt";
$url = "http://where.yahooapis.com/geocode?q=".
		urlencode($location)."&appid=[der-api-key]";
echo file_get_contents($url);

2) Detaillierte Angabe der Adresse:

$address = array("street" => "Neckarstraße",
				 "house" => 15,
				 "postal" => 64283,
				 "city" => "Darmstadt",
				 "country" => "DE");

$url = "http://where.yahooapis.com/geocode?".
	    http_build_query($address,"","&").
		"&appid=[der-api-key]";
echo file_get_contents($url);

Bei der detaillierteren Variante fällt der „q“-Parameter weg und es werden stattdessen die Einzelangaben gemacht (es können auch weniger Details angegeben werden). Inkorrekte Postleitzahlen / Tippfehler werden korrigiert.

Adresse zu einer Koordinate finden

$coords = array("lat" => 48.1431,
				"long" => 8.4176);

$url = "http://where.yahooapis.com/geocode?q=".
		$coords['lat'].",".$coords['long'].
		"&gflags=R&appid=[der-api-key]";
echo file_get_contents($url);

Auch hier wird wieder der „q“-Parameter verwendet. Die Koordinaten dann einfach mit Komma getrennt hinterher. Zu beachten ist der „gflags=R“ Parameter, der das Resolven der Koordinaten veranlasst.

Weitere Finessen

• Outputformat: Standardmäßig kommt das Result in XML zurück. Mit Parameter flags=J kommt JSON bei euch an, mit flags=P serialisiertes PHP. Ich bin mit dem serialisierten PHP sehr gut gefahren
• Quality-Index: Zu jeder gefundenen Adresse (ja, es können auch mehrere passende sein, die in der Response aufgeführt werden) wird ein quality-index mitgeliefert. Dieser variiert zwischen 0 und 99, kann aber im Standard-Suchfall nach einer Adresse maximal 87 ergeben (höhere Werte sind nur für POI’s wie bspw. den Eiffelturm möglich).
• Sprache des Outputs: Per Parameter locale=de_DE kommt Deutsch zurück, default ist logischerweise Englisch.

Man kann also sehr gut mit dem Placefinder auskommen. Für weiteres sei auf die sehr gute Dokumentation verwiesen, in der u.a. auch noch der Quality-Index genau aufgeschlüsselt wird und ein paar weitere Parameter zu finden sind

Weitere Posts:

• Open Streetmap API Tutorial: Umkreissuche
• PHP-Errors zu Exceptions konvertieren
• Streams
• Umkreissuche: Lat/Long und der Radius
• Testen mal anders: phpt