Home » Specifications » OpenSearch » Extensions » Geo » 1.0 » Draft 1

Contents

[edit] Notice

This is a draft document for public review.

A new version of this document is available here

[edit] Introduction

Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name.

The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard.

Update : New draft available (see here)


[edit] Namespace

Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct.

[edit] Example

Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters.

 <?xml version="1.0" encoding="UTF-8"?>
 <OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"
                        xmlns:geo="http://a9.com/-/opensearch/extensions/geo/1.0/">
   <ShortName>Web Search</ShortName>
   <Description>Use Example.com to search the Web.</Description>
   <Tags>example web</Tags>
   <Contact>admin@example.com</Contact>
   <Url type="application/vnd.google-earth.kml+xml"
       template="http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml"/>
   <Url type="application/atom+xml"
       template="http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom"/>
   <Url type="application/rss+xml"
       template="http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss"/>
   <Url type="text/html"
       template="http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}"/>
   <LongName>Example.com Web Search</LongName>
   <Image height="64" width="64" type="image/png">http://example.com/websearch.png</Image>
   <Image height="16" width="16" type="image/vnd.microsoft.icon">http://example.com/websearch.ico</Image>
   <Query role="example" searchTerms="cat" />
   <Developer>Example.com Development Team</Developer>
   <Attribution>
       Search data Copyright 2005, Example.com, Inc., All Rights Reserved
   </Attribution>
   <SyndicationRight>open</SyndicationRight>
   <AdultContent>false</AdultContent>
   <Language>en-us</Language>
   <OutputEncoding>UTF-8</OutputEncoding>
   <InputEncoding>UTF-8</InputEncoding>
 </OpenSearchDescription>

[edit] Namespace

The XML namespace of the OpenSearch Geo Extension is:

http://a9.com/-/opensearch/extensions/geo/1.0/

This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document.

[edit] Parameters

[edit] The "locationString" parameter

Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Warning : This element was changed on Draft 2 (see here)


Example URL template:

 http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:locationString?}&format=rss

Example request:

 http://example.com/?q=pizza&l=boston&format=rss

[edit] The "lat" and "lon" parameters

Replaced with the "latitude, longitude", respectively, in decimal degrees in EPSG:4326 (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result.

Example URL template:

 http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss

Example request:

 http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss

[edit] The "radius" parameters

The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface.

Example:

 http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss

[edit] The "box" parameter

Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a EPSG:4326 decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner.

 geo:box ~ west, south, east, north

Example URL template:

 http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss

Example request:

 http://example.com/?q=pizza&bbox=-111.032,42.943,-119.856,43.039&format=rss

[edit] The "polygon" parameter

Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon.

Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian).

Warning : This element was changed on Draft 2 (see here)

Example URL template:

 http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&format=rss

Example request:

 http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss

[edit] Optional Parameters

The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension.

Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters:

Example:

 http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml

[edit] Geo response elements

The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the OpenSearch response definition for a general overview of the response options.

The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements.

[edit] Atom Response

Example request:

 http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"

Example response:

   <?xml version="1.0" encoding="UTF-8"?>
    <feed xmlns="http://www.w3.org/2005/Atom" 
          xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
          xmlns:georss="http://www.georss.org/georss">
      <title>Example.com Search: New York history</title> 
      <link href="http://example.com/New+York+history"/>
      <updated>2003-12-13T18:30:02Z</updated>
      <author> 
        <name>Example.com, Inc.</name>
      </author> 
      <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>
      <opensearch:totalResults>4230000</opensearch:totalResults>
      <opensearch:startIndex>21</opensearch:startIndex>
      <opensearch:itemsPerPage>10</opensearch:itemsPerPage>
      <opensearch:itemsPerPage>10</opensearch:itemsPerPage>
      <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/>
      <link rel="alternate" href="http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/>
       <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml"/>
      <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box>
      <entry>
        <title>New York History</title>
        <link href="http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html"/>
        <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
        <updated>2003-12-13T18:30:02Z</updated>
        <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line>
        <content type="text">
          ... Union Square.NYC - A virtual tour and information on 
          businesses ...  with historic photos of Columbia's own New York 
          neighborhood ... Internet Resources for the City's History. ...
        </content>
      </entry>
    </feed>

[edit] KML Response

KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries.

Example request:

 http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"

Example response:

   <?xml version="1.0" encoding="UTF-8"?>
   <kml xmlns="http://earth.google.com/kml/2.2"
     xmlns:atom="http://www.w3.org/2005/Atom"
     xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
     xmlns:opensearchgeo="http://a9.com/-/opensearch/extensions/geo/1.0/">
      <opensearch:totalResults>4230000</opensearch:totalResults>
      <opensearch:startIndex>21</opensearch:startIndex>
      <opensearch:itemsPerPage>10</opensearch:itemsPerPage>
      <opensearch:itemsPerPage>10</opensearch:itemsPerPage>
      <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/>
      <atom:link rel="alternate" href="http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/>
      <atom:link rel="alternate" href="http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom" type="application/atom+xml"/>       
   <Document>
     <name>NYCHistory.kml</name>
     <open>1</open>
     <Placemark>
       <name>New York History</name>
       <atom:link>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</atom:link>
       <LineString>
         <coordinates>
           -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 
           -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0
         </coordinates>
       </LineString>
     </Placemark>
   </Document>
   </kml>

[edit] Author

Andrew Turner <ajturner@highearthorbit.com>

[edit] Contributors

DeWitt Clinton <dewitt@opensearch.org>

[edit] License

This document is made available subject to the terms of the Creative Commons Attribution-ShareAlike 2.5 License.