Today we announced an update to GeoPlanet that adds a few new features. This topic provides information about each of these new features and examples for using them.
1) New "callback" query parameter
The callback parameter is used with the JSON response format (and new GeoJSON response format) to implement
JSONP. The callback parameter is a JavaScript function name that will be prepended to the JSON data (along with surrounding parentheses). This allows a GeoPlanet request to be used as the src parameter for a <script> tag and execute a previously defined JavaScript function.
Example:
The request
http://where.yahooapis.com/v1/place/12521721?appid=[yourappid]&format=json&callback=myfunc returns the following:
myfunc({"places":{"place":[{"woeid":12521721,"placeTypeName":"Airport","placeTypeName attrs":{"code":14},
"name":"San Francisco International Airport","country":"United States","country attrs":{"type":"Country","code":"US"},
"admin1":"California","admin1 attrs":{"type":"State","code":"US-CA"},
"admin2":"San Mateo","admin2 attrs":{"type":"County","code":""},
"admin3":"","locality1":"Millbrae","locality1 attrs":{"type":"Town"},"locality2":"",
"postal":"94128","postal attrs":{"type":"Zip Code"},"centroid":{"latitude":37.614712,"longitude":-122.391808},
"boundingBox":{"southWest":{"latitude":37.601822,"longitude":-122.408089},
"northEast":{"latitude":37.627602,"longitude":-122.375526}},
"uri":"http:\/\/where.yahooapis.com\/v1\/place\/12521721","lang":"en-us"}],"start":0,"count":1,"total":1}});This can be included in an HTML document:
<script src="http://where.yahooapis.com/v1/place/12521721?appid=[yourappid]&format=json&callback=myfunc"></script>2) New "GeoJSON" response format
The GeoJSON response format returns geographic information using tags defined by
draft version 6 of the GeoJSON specification. In particular, all place resources are defined as Point types, the place centroid is returned in the coordinates element, and the place bounding box is returned in the bbox element.
Example:
The request
http://where.yahooapis.com/v1/place/12521721?appid=[yourappid]&format=geojson returns the following:
{"places":{"place":[{"woeid":12521721,"placeTypeName":"Airport","placeTypeName attrs":{"code":14},
"name":"San Francisco International Airport","country":"United States","country attrs":{"type":"Country","code":"US"},
"admin1":"California","admin1 attrs":{"type":"State","code":"US-CA"},
"admin2":"San Mateo","admin2 attrs":{"type":"County","code":""},
"admin3":"","locality1":"Millbrae","locality1 attrs":{"type":"Town"},"locality2":"",
"postal":"94128","postal attrs":{"type":"Zip Code"},"type":”Point”,”coordinates”:[-122.391808,37.614712],
"bbox":[-122.408089,37.601822,-122.375526,37.627602],
"uri":"http:\/\/where.yahooapis.com\/v1\/place\/12521721","lang":"en-us"}],"start":0,"count":1,"total":1}}3) New $and filter for /places collection
The $and filter allows two other filters to be provided for requests for the /places collection. This means that a request can filter by place type as well as by place name. The $and filter takes two arguments that are filters themselves.
Example:
The request
http://where.yahooapis.com/v1/places$and(.q(Long+Island),.type(Town));count=0?appid=[yourappid] returns all places named “Long Island” that are towns.
Multiple place types can be provided. For example:
The request
http://gws1.dev01.maps.sp1.yahoo.com/v1/places$and(.q(Long+Island),.type(Town,Suburb));count=0?appid=[yourappid] returns all places named “Long Island” that are towns or suburbs.
4) New placetype resource
The placetype resource allows information to be returned about a single place type. This resource can simplify applications that want to use place type information.
Example:
The request
http://where.yahooapis.com/v1/placetype/10)?appid=[yourappid] returns the following:
<placeType yahoo:uri="http://where.yahooapis.com/v1/placetype/10" xml:lang="en-us">
<placeTypeName code="10">Local Administrative Area</placeTypeName>
</placeType>5) Long description for placetype resource (and placetypes collection)
The placeType resource now has a long representation that includes a one line description for the place type. This can help users understand how the place type is used. The long representation can be selected for the placetypes collection as well.
Example:
The request
http://where.yahooapis.com/v1/placetype/10)?appid=[yourappid]&select=long returns the following:
<placeType yahoo:uri="http://where.yahooapis.com/v1/placetype/10" xml:lang="en-us">
<placeTypeName code="10">Local Administrative Area</placeTypeName>
<placeTypeDescription>One of the tertiary administrative areas within a country</placeTypeDescription>
</placeType>We hope you find these new features useful. If you have suggestions for improving GeoPlanet, please let us know!
Eddie Babcock
Principal Engineer, Yahoo! Geo Technologies
