GeoPlanet Web Service

Base URI

Yahoo! GeoPlanet is a REST Web service, accessible at the following URI:

http://where.yahooapis.com/v1[parameters]

Requests to GeoPlanet are sent as HTTP GET messages, using a URI to indicate what resource or collection is desired, and HTTP headers to provide context for the request. A GeoPlanet URI is composed of the base URI, followed by a resource or collection name, an optional filter description, optional matrix parameters, and optional and required query parameters. A GeoPlanet request may have several headers describing the desired content type and language for the response.

The GeoPlanet Web service supports only the HTTP GET method. Other HTTP methods are not supported. Therefore, the Web service is read-only.

Resources and Collections

A resource identifies an object (commonly referred to as "nouns" in REST terminology). For example, a named place is a resource, and a unique URL exists to retrieve it. Resources are referred to in the singular ("place," "parent," etc.).

A collection is a list of resources. Whenever zero or more objects can be returned, a collection is used. Collections are referred to in the plural ("ancestors," "children," etc.).

Filters

The Web service supports a number of different filters that allow you to select a subset of potentially large collections. Filters follow the collection name they refer to. A filter description consists of the filter name, an open parenthesis, a list of numeric or string values separated by commas, and a close parenthesis. If a string value contains a comma, the string value must be enclosed in single quotes. A filter name begins with either a period or a dollar sign.

The following filters are provided by the Web service:

Filter Collection Examples Description
.q(place [, focus]) /places

.q(Springfield)

.q('New%20York')

.q('Clo%2A')

.q('Tokyo', 'JP')

 Returns places matching specified place and optional focus. This filter can be specified without the filter name (q). This filter is mutually exclusive with the woeid filter.

The specified place can be any URL-encoded text that does not contain the following characters: ,()*!@#$&=|;:?/. If place is enclosed in single quotes, commas can be used.

Focus can be either an ISO-3166-1 country code or a WOEID.

For a "startswith" filter, specify the place as a string followed by an asterisk (*), encoded as %2A. Towns are returned in probability order. A maximum of 200 places can be returned per request.

.woeid(woeid [, woeid ...]) /places .woeid(1,2,3) Returns places matching specified Where On Earth Identifer (WOEID). Up to ten WOEIDs may be specified. This filter is mutually exclusive with the q filter.
.type(placetype [,placetype ...]) /places .type(12) Returns places matching the specified place type code or language-specific name. Up to ten place type codes or names may be provided by separating them with commas. For more information, see Place Types.
.type(placetype)

/belongtos

/children

/placetypes

.type(12) Returns places or place types matching specified place type. Up to ten place types may be provided by separating them with commas. This filter can be specified without the filter name (type).
.degree(degree) /neighbors

/children

 .degree(2) Returns places that have more distant relationships (that is, neighbors of neighbors).
$and(filter, filter) /places $and(.q(Springfield), .type(22)) Returns places matching the intersection of two filters. The $and operator may not be one of the two filters.

Matrix Parameters

The Web services supports several parameters (name/value pairs) called "matrix parameters" that allow users to request small portions of potentially large collections. Matrix parameters follow the collection name or filter they refer to. They are preceded and separated by a semi-colon, and consist of the parameter name, an equals sign, and a numeric or string value. Values may not contain semi-colons, equals signs, or question marks.

The following matrix parameters are supported by the Web service:

Parameter Default Example Description  
start 0 start=1 Skip first N results  
count

1 for /places

100 for /place/types

10 for others

count=5 Return a maximum of N results. A count of 0 is interpreted as "no maximum" (all resources).  

Query Parameters

The Web service supports several parameters (name/value pairs) called "query parameters" that allow users to specify a particular language or format for the response. Query parameters follow the resource or collection name, filter, and any matrix parameters. They are preceded by a question mark and separated by ampersands and consist of the parameter name, an equals sign, and a numeric or string value. Values may not contain question marks or ampersands.

The following query parameters are supported by the Web service:

Parameter Collection Default Example Description
appid all (required) appid=336690 Grants authorization to use the web service; required for all requests.
lang

/places

/place

(Accept-Language header) lang=fr-CA Return names in specified language (RFC 4646). Overrides language indicated by Accept-Language header.
format all (Accept header) format=json Return results in specified format. Allowed values:xml, json, geojson. Overrides format indicated by Accept header; required if the request does not include an Accept header.
callback all (none) callback=myfunc Return JSON results wrapped in a JavaScript function call; only used when format=json or format=geojson.
view

/places

/place

all others

long

long

short

view=long Return results in specified representation: short, long.
select same as view same as view same as view Returns same results as view parameter.

Headers

The Web service supports several HTTP headers that allow users to specify the desired content type and language for the response. These headers may be overridden by query parameters.

The following headers are supported by the Web service:

Header Example Description
Accept application/xml Desired content type:

application/xml: XML

application/json: JSON

Accept-Language en_US Desired language (RFC 4646)

Response Formats

The GeoPlanet Web service supports the following response formats:

XML

eXtensible Markup Language (XML) is an open standard specification for serializing structured data.

JSON

JavaScript Object Notation (JSON) is a light-weight data interchange format, often used to serialize structured data.

GeoJSON

GeoJSON is a dialect of JSON that can be used to represent geographic features; GeoPlanet implements draft version 6 of the GeoJSON specification. In particular, all places are represented as points, the centroid for places is contained in the coordinates array element, and the bounding box for places is contained in the bbox array element

The response format is determined from the value of the Accept header included with the request, and can be overridden using the format query parameter. If there is no Accept header, or if the Accept header does not refer to a supported response format, the format parameter must be provided and have a valid value. Otherwise, a "406 Not acceptable" message will be returned.

Example 5. Place Resource in XML format


Example 6. Place Resource in JSON format


Example 7. Place Resource in GeoJSON format


Response Errors

The Web service can return the following errors:

Error Code Cause Solution
400 Bad Request The appid parameter was invalid or not specified. Register your application with Yahoo! to get an appid and provide the appid parameter for each GeoPlanet request.
400 Bad Request The q filter was missing or incorrectly specified for this resource. Provide the q filter in requests for the /places collection.
404 Not Found The URI has no match in the display map. Make sure that you have spelled the resource correctly and are using one of the supported filters for the /places collection.
406 Not Acceptable The requested representation is not available for this resource. Include an Accept header or format parameter with a supported value.

Response Data Elements

The Web service returns one of four documents depending on the collection or resource requested:

Document Collection or Resource Description
places

/place/{woeid}/belongtos

/place/{woeid}/neighbors

/place/{woeid}/siblings

/place/{woeid}/children

/place/{woeid}/descendants

/continents

/oceans

/seas

/countries

/states

/counties

/districts

 container for place elements
place /place/{woeid}/common container for place subelements
placeTypes /placetypes container for placeType elements
placeType /placetype container for placeType subelements
error all container for error subelements

The order of the elements within the places document depends on the collection requested:

Collection Place Order
/places probability
/place/{woeid}/ancestors smallest to largest
/place/{woeid}/belongtos smallest to largest
/place/{woeid}/neighbors nearest to farthest
/place/{woeid}/siblings woeid
/place/{woeid}/children woeid
/place/{woeid}/descendants children, grandchildren, etc
/continents woeid
/oceans woeid
/seas woeid
/countries woeid
/states

/admin1s

woeid
/counties

/admin2s

woeid
/districts

/admin3s

woeid

The following subelements are contained in the place element:

Element Supported Representations Description
woeid short, long Where On Earth Identifer
placeTypeName short, long localized name of the place type; the code attribute identifies the place type in a language-free manner; see Place Types
name short, long localized name of the place
country long localized name of the country
admin1 long localized name of the subcountry admin area
admin2 long localized name of the subadmin1 admin area
admin3 long localized name of the subadmin2 admin area
locality1 long localized name of a populated place such as a town or village
locality2 long localized name of the sublocality such as a suburb or neighborhood)
postal long postal code
centroid long the longitude and latitude of a single point that best represents a place, based on factors such as cultural influence or population
boundingBox long the bounding box of the place, represented by the minimum and maximum values of the longitudes and latitudes associated with the place
areaRank long code representing the size of the place (see the following table)
popRank long code representing the population size (see the following table)

The areaRank and popRank elements represent the area and population of a place. The elements contain codes instead of actual values because of variations in determining area and population. These codes can be used to reorder results by area or population, or used to ignore places outside a certain range of area or population. The following table lists the codes:

Code for areaRank and popRank Approximate Area (Square Kilometers) Approximate Population (Number of Residents)
0 unknown area unknown population
1 1-3 1-3
2 3-10 3-10
3 10-30 10-30
4 30-100 30-100
5 100-300 100-300
6 300-1,000 300-1,000
7 1,000-3,000 1,000-3,000
8 3,000-10,000 3,000-10,000
9 10,000-30,000 10,000-30,000
10 30,000-100,000 30,000-100,000
11 100,000-300,000 100,000-300,000
12 300,000-1,000,000 300,000-1,000,000
13 1,000,000-3,000,000 1,000,000-3,000,000
14 3,000,000-10,000,000 3,000,000-10,000,000
15 10,000,000-30,000,000 10,000,000-30,000,000
16 30,000,000-100,000,000 30,000,000-100,000,000
17 100,000,000-300,000,000 100,000,000-300,000,000
18 300,000,000-1,000,000,000 300,000,000-1,000,000,000
19 N/A 1,000,000,000-3,000,000,000
20 N/A 3,000,000,000-10,000,000,000

The following subelements are contained in the placeType element:

Element Description
placeTypeName localized name of the place type

The placetypeName element includes an attribute containing a placeType code that can be used instead of the name. Each place has a single placeType . The following table lists the placeType codes:

placeType Code Description
7 A populated settlement such as a city, town, village
8 A primary administrative area within a country
9 A secondary administrative area within a country
10 A tertiary administrative area within a country
11 A partial or full postal code
12 One of the countries or dependent territories defined by the ISO 3166-1 standard
13 An island
14 An airport
15 A water feature such as a river, canal, lake
16 A land feature such as a park, mountain, beach
17 An uncategorized place
19 An area covering multiple countries
20 A point of interest such as a school, hospital, tourist attraction
22 A subdivision of a town such as a quarter, suburb or neighborhood
24 A place known by a colloqial name (such as Silicon Valley)
25 An area known within a specific context such as MSA or area code
26 A former/historical primary administrative area with a country
27 A former/historial secondary administrative area within a country
29 One of the seven major land masses on the Earth
31 An area defined by the Olsen standard (tz database)
33 A housing development or subdivsion known by a name
35 A former/historial populated settlement
37 One of the five major bodies of water on the Earth
38 An area of open water smaller than an ocean such as a sea, bay, gulf, channel

The following subelements are contained in the error element:

Element Description
description error code and name
detail additional information about the error

Table of Contents