The Geo Location Rest API allows users to retrieve likely geographical locations given text, to retrieve likely geographical locations given phrases characterizing the most the formers locations and/or to identify phrases characterizing a specific location.
For researchers or engineers this web service can be seen as a search platform through which the requested information is pulled out from the structured index. You only have to extract the right information using the proper search constraints.
Geo Location is a REST API, accessible at the following URI:
http://glocal.research.yahoo.com/geo-location/rest-api/rest.php?[parameters]
The query parameter must be defined at least to do a successful request. The rest of the parameters are optional, they can be combined in no specific order.
| Parameter | Value | Example | Description | Default Value |
|---|---|---|---|---|
| query | free text | Barcelona, The Wall, Paella | Free text. It can be any sequence of terms. | This field is mandatory. It has no default value. |
| source | free text | Flickr, Twitter, TwitterTag | Dataset to tap into | Flickr |
| template | String | xml-basic, xml-geo-info, xml-compact, json-compact | The format of the backend response. | xml-basic |
| match | String | OR, AND | The query boolean operator. If set to AND, all the query terms must occur in the document. If set to OR, at least one query term must occur in the document so to be retrieved. | OR |
| order | String | ASC, DESC | The order of the retrieved locations with respect to their relevance score. | DESC |
| normalize | Boolean | TRUE, FALSE | A boolean flag indicating if the relevance scores of the retrieved documents should be normalized or not. The normalized range is [0-1]. | FALSE |
| continent | string | Europe, North America | *Continent name | None |
| country | string | Spain, Italy | *Country name | None |
| state | string | California (USA), Gerona (Spain) | *State name | None |
| county | string | Davidson (Tennessee/USA), Gerona (Catalauña/Spain) | *County name. The meaning of county varies depending on the country, for Spain county means region. | None |
| town | string | Madrid, London | *Town name | None |
| zip | integer | 90210 (Beverly Hills), 28033 (Madrid) | *The 5 digit zip code | None |
| total-hits | integer | 1000 | The number of results being returned. The value must be a positive integer. | The default value is 10 |
Be careful when using the geographic parameters - continent, country, state, county, town, zip - they need to be combined in a logical way, if they are contradictory (i.e.: the zip does not exist within a given country) it might return an empty result..
| Field | Description |
|---|---|
| result | Main XML element. The attributes are:
|
| hit | XML element of a retrieved location. The attributes are:
|
| geo-box | geographic coordinates of the 1km² gridcell that contains the result hit. The gridcell is defined by the northwest (top-left) and the southeast (bottom-right) coordinates. |
| Continent | Continent in which the result is located |
| Country | Country in which the result is located |
| State | State in which the result is located |
| County | County in which the result is located |
| Town | Town in which the result is located |
| Zip | Zip code in which the result is located |
| salient-phrases | The top N salient phrases characterizing the most the given location. The subelements are:
|
<xml>
<result total="10">
<hit lat="39.314768" lon="-0.318902" score="-7.937964">
<geo-box>
<north-west>
<lat>39.31926</lat>
<lon>-0.323394</lon>
</north-west>
<south-east>
<lat>39.310277</lat>
<lon>-0.31441</lon>
</south-east>
</geo-box>
<zip></zip>
<town>Sueca</town>
<county>Valencia</county>
<state>Valencia</state>
<country>Spain</country>
<continent>Europe</continent>
<salient-phrases>
<salient-phrase value="8">Agua</salient-phrase>
<salient-phrase value="3">Paisaje</salient-phrase>
<salient-phrase value="2">Arroz</salient-phrase>
<salient-phrase value="5">Atardecer</salient-phrase>
<salient-phrase value="3">Boat</salient-phrase>
<salient-phrase value="3">Reflejo</salient-phrase>
<salient-phrase value="2">Colores</salient-phrase>
<salient-phrase value="6">L Albufera</salient-phrase>
<salient-phrase value="20">El Palmar</salient-phrase>
<salient-phrase value="5">La Albufera</salient-phrase>
<salient-phrase value="5">Lago</salient-phrase>
<salient-phrase value="3">Nubes</salient-phrase>
<salient-phrase value="3">Barraca</salient-phrase>
<salient-phrase value="2">Paella</salient-phrase>
<salient-phrase value="3">Embarcadero</salient-phrase>
<salient-phrase value="7">Barcas</salient-phrase>
<salient-phrase value="3">Reflejos</salient-phrase>
<salient-phrase value="4">Sol</salient-phrase>
<salient-phrase value="2">Cielo</salient-phrase>
<salient-phrase value="9">Barca</salient-phrase>
</salient-phrases>
</hit>
...
</result>
</xml>
Retrieve likely locations related to the named-entity 'Gaudi':
http://glocal.research.yahoo.com/geo-location/rest-api/rest.php?query=gaudi
Retrieve likely implicit locations for the term 'paella' restricting the geographic scope to the county of 'Valencia':
http://glocal.research.yahoo.com/geo-location/rest-api/rest.php?query=paella&county=Valencia
(Advanced request) Retrieve implicit locations for the term 'nevada' restricting the geographic scope, and adding parameters for template, normalize, match and hits:
http://glocal.research.yahoo.com/geo-location/rest-api/rest.php?&query=nevada&template=xml-compact&match=OR&total-hits=10&normalize=FALSE&continent=NORTH AMERICA&country=UNITED STATES&state=NEVADA&county=CLARK&town=LAS VEGAS
Geo Location Rest API returns the following Errors in XML format:
| Code | Description | Situation |
|---|---|---|
| 100 | No input parameters. | No parameters defined. |
| 101 | Bad request, empty query parameter. You must define the query parameter at least. | The query parameter needs to be at least defined to issue a succesful request. |
| 102 | Bad request, empty parameter(s). Please review your parameters. | Parameters have been specified but they have no value or empty. |
| 103 | Bad request, invalid parameter(s). | An unexpected parameter has been used. It might be a syntax error. |
The GeoLocation Rest API is unlimited at this moment.