MarkLogic Server
XQUERY API DOCUMENTATION
4.1
All XQuery Functions
MarkLogic Built-In Functions
XQuery Library Modules
CPF Functions
W3C-Standard Functions
  W3C XQuery Reference
W3C XQuery Functions
W3C XQuery Language
This page was generated
August  8,  2011
2:24  AM
XQuery Built-In and Modules Function Reference

Module: Geospatial Supporting Functions - GEO Functions

The Geo module provides support for geospatial queries using GML, KML, GeoRSS/Simple, or Metacarta Geospatial markup.

To use the Geo module as part of your own XQuery module, include the following line in your XQuery prolog:

import module namespace geo = "http://marklogic.com/geospatial" at "/MarkLogic/geospatial/geospatial.xqy";

The library namespace prefix geo is not predefined in the server.
Function Summary
geo:box Create a cts:point value from an element representing a box in one of the supported markup vocabularies.
geo:circle Create a cts:circle value from a radius and an element representing a point in one of the supported markup vocabularies.
geo:geospatial-query Returns a cts:query matching points within given regions.
geo:geospatial-query-from-elements Returns a cts:query matching points within given regions.
geo:interior-polygon Create a sequence of cts:polygon values from a polygon element in one of the supported markup vocabularies.
geo:point Create a cts:point value from an element representing a point in one of the supported markup vocabularies.
geo:polygon Create a cts:polygon value from a sequence of point elements in one of the supported markup vocabularies.
geo:polygon Create a cts:polygon value from a polygon element in one of the supported markup vocabularies.
Function Detail
geo:box(
$box as element()
)  as   cts:box
Summary:

Create a cts:point value from an element representing a box in one of the supported markup vocabularies.

Parameters:
$box : An element representing a box.

Example: 
  xquery version "1.0-ml";
  import module namespace geo = "http://marklogic.com/geospatial"
         at "/MarkLogic/geospatial/geospatial.xqy";
  declare namespace kml= "http://earth.google.com/kml/2.0";

  geo:box(
     <kml:LatLongBox>
       <kml:north>30</kml:north>
       <kml:south>12.5</kml:south>
       <kml:east>-122.24</kml:east>
       <kml:west>-127.24</kml:west>
     </kml:LatLongBox>)
geo:circle(
$radius as xs:double,
$center as element()
)  as   cts:circle
Summary:

Create a cts:circle value from a radius and an element representing a point in one of the supported markup vocabularies.

Parameters:
$radius : The radius of the circle, in miles.
$center : An element representing the point at the center of the circle.

Example: 
  xquery version "1.0-ml";
  import module namespace geo = "http://marklogic.com/geospatial"
         at "/MarkLogic/geospatial/geospatial.xqy";

  geo:circle(47, <Dot Latitude="12.5" Longitude="-127.24"/>)
geo:geospatial-query(
$regions as cts:region*,
[$options as xs:string*],
[$weight as xs:double?]
)  as   cts:query
Summary:

Returns a cts:query matching points within given regions.

Parameters:
$regions : One or more geographic boxes, circles, polygons, or points. Where multiple boxes, circles, polygons, or points are specified, the query matches if any box, circle, polygon, or point matches.
$options (optional): Options to this query. The default is ().

Options include:

"coordinate-system=wgs84"
Use the WGS84 coordinate system.
"boundaries-included"
Points on boxes' and circles' boundaries are counted as matching. This is the default.
"boundaries-excluded"
Points on boxes' and circles' boundaries are not counted as matching.
"boundaries-latitude-excluded"
Points on boxes' latitude boundaries are not counted as matching.
"boundaries-longitude-excluded"
Points on boxes' longitude boundaries are not counted as matching.
"boundaries-south-excluded"
Points on the boxes' southern boundaries are not counted as matching.
"boundaries-west-excluded"
Points on the boxes' western boundaries are not counted as matching.
"boundaries-north-excluded"
Points on the boxes' northern boundaries are not counted as matching.
"boundaries-east-excluded"
Points on the boxes' eastern boundaries are not counted as matching.
"boundaries-circle-excluded"
Points on circles' boundary are not counted as matching.
$weight (optional): A weight for this query. The default is 1.0.

Usage Notes:

The point value is expressed in the content of the element as a pair of numbers, separated by whitespace and punctuation (excluding decimal points and sign characters).

Point values and boundary specifications of boxes are given in degrees relative to the WGS84 coordinate system. Southern latitudes and Western longitudes take negative values. Longitudes will be wrapped to the range (-180,+180) and latitudes will be clipped to the range (-90,+90).

If the northern boundary of a box is south of the southern boundary, no points will match. However, longitudes wrap around the globe, so that if the western boundary is east of the eastern boundary, then the box crosses the anti-meridian.

Special handling occurs at the poles, as all longitudes exist at latitudes +90 and -90.

The query constructed will examine points in all the supported geospatial markup vocabularies. If not all these vocabularies will be in use, it may be more efficient to use the query constructors for just the vocabulary or vocabularies that are in actual use.


Example: 
xquery version "1.0-ml";
(: create a document with test data :)
declare namespace gml= "http://www.opengis.net/gml";
declare namespace georss= "http://www.georss.org/georss";

xdmp:document-insert("/points.xml",
<root xmlns:geo="http://marklogic.com/geospatial">
  <item><gml:Point><gml:pos>10.5 30.0</gml:pos></gml:Point></item>
  <item><georss:point>15.35 35.34</georss:point></item>
  <item><Dot Latitude="5.11" Longitude="40.55"/></item>
</root> );

xquery version "1.0-ml";
import module namespace geo = "http://marklogic.com/geospatial"
   at "/MarkLogic/geospatial/geospatial.xqy";
declare namespace gml= "http://www.opengis.net/gml";
declare namespace georss= "http://www.georss.org/georss";
declare namespace kml= "http://earth.google.com/kml/2.0";

cts:search(doc("/points.xml")//item, 
  geo:geospatial-query(
    geo:box(
      <gml:Envelope>
        <gml:lowerCorner>10.0 35.0</gml:lowerCorner>
        <gml:upperCorner>20.0 40.0</gml:upperCorner>
      </gml:Envelope>)
  ))
(:
  returns the following node: 
  <item><georss:point>15.35 35.34</georss:point></item>
:)
,

cts:search(doc("/points.xml")//item, 
  geo:geospatial-query(geo:box(
    <kml:LatLongBox>
      <kml:north>20.0</kml:north>
      <kml:south>10.0</kml:south>
      <kml:east>35.0</kml:east>
      <kml:west>40.0</kml:west>
    </kml:LatLongBox>
  )))
(:
  returns the following nodes (wrapping around the Earth):
  <item><gml:Point><gml:pos>10.5 30.0</gml:pos></gml:Point></item>
:)
,

cts:search(doc("/points.xml")//item, 
  geo:geospatial-query(
    cts:box(10.0, 35.0, 20.0, 40.0)))
(:
  returns the following node:
  <item><georss:point>15.35 35.34</georss:point></item>
:)
geo:geospatial-query-from-elements(
$regions as element()*,
[$options as xs:string*],
[$weight as xs:double?]
)  as   cts:query
Summary:

Returns a cts:query matching points within given regions.

Parameters:
$regions : One or more geographic boxes, circles, polygons, or points, represented by elements in one of the supported vocabularies. Where multiple boxes, circles, polygons, or points are specified, the query matches if any box, circle, polygon, or point matches.
$options (optional): Options to this query. The default is ().

Options include:

"coordinate-system=wgs84"
Use the WGS84 coordinate system.
"boundaries-included"
Points on boxes' and circles' boundaries are counted as matching. This is the default.
"boundaries-excluded"
Points on boxes' and circles' boundaries are not counted as matching.
"boundaries-latitude-excluded"
Points on boxes' latitude boundaries are not counted as matching.
"boundaries-longitude-excluded"
Points on boxes' longitude boundaries are not counted as matching.
"boundaries-south-excluded"
Points on the boxes' southern boundaries are not counted as matching.
"boundaries-west-excluded"
Points on the boxes' western boundaries are not counted as matching.
"boundaries-north-excluded"
Points on the boxes' northern boundaries are not counted as matching.
"boundaries-east-excluded"
Points on the boxes' eastern boundaries are not counted as matching.
"boundaries-circle-excluded"
Points on circles' boundary are not counted as matching.
$weight (optional): A weight for this query. The default is 1.0.

Usage Notes:

The point value is expressed in the content of the element as a pair of numbers, separated by whitespace and punctuation (excluding decimal points and sign characters).

Point values and boundary specifications of boxes are given in degrees relative to the WGS84 coordinate system. Southern latitudes and Western longitudes take negative values. Longitudes will be wrapped to the range (-180,+180) and latitudes will be clipped to the range (-90,+90).

If the northern boundary of a box is south of the southern boundary, no points will match. However, longitudes wrap around the globe, so that if the western boundary is east of the eastern boundary, then the box crosses the anti-meridian.

Special handling occurs at the poles, as all longitudes exist at latitudes +90 and -90.

The query constructed will examine points in all the supported geospatial markup vocabularies. If not all these vocabularies will be in use, it may be more efficient to use the query constructors for just the vocabulary or vocabularies that are in actual use.

This function will take into account interior polygons, if any, and properly construct the query to account for them.


Example: 
xquery version "1.0-ml";
(: create a document with test data :)
declare namespace gml= "http://www.opengis.net/gml";
declare namespace georss= "http://www.georss.org/georss";

xdmp:document-insert("/points.xml",
<root xmlns:geo="http://marklogic.com/geospatial">
  <item><gml:Point><gml:pos>10.5 30.0</gml:pos></gml:Point></item>
  <item><georss:point>15.35 35.34</georss:point></item>
  <item><Dot Latitude="5.11" Longitude="40.55"/></item>
</root> );

xquery version "1.0-ml";
import module namespace geo = "http://marklogic.com/geospatial"
   at "/MarkLogic/geospatial/geospatial.xqy";
declare namespace gml= "http://www.opengis.net/gml";
declare namespace georss= "http://www.georss.org/georss";
declare namespace kml= "http://earth.google.com/kml/2.0";

cts:search(doc("/points.xml")//item, 
  geo:geospatial-query-from-elements(
    <gml:Envelope>
      <gml:lowerCorner>10.0 35.0</gml:lowerCorner>
      <gml:upperCorner>20.0 40.0</gml:upperCorner>
    </gml:Envelope>
  ) )
(:
  returns the following node: 
  <item><georss:point>15.35 35.34</georss:point></item>
:)
,

cts:search(doc("/points.xml")//item, 
  geo:geospatial-query-from-elements(
    <kml:LatLongBox>
      <kml:north>20.0</kml:north>
      <kml:south>10.0</kml:south>
      <kml:east>35.0</kml:east>
      <kml:west>40.0</kml:west>
    </kml:LatLongBox>
  ))
(:
  returns the following nodes (wrapping around the Earth):
  <item><georss:point>15.35 35.34</georss:point></item>
  <item><gml:Point><gml:pos>10.5 30.0</gml:pos></gml:Point></item>
:)
geo:interior-polygon(
$polygon as element()
)  as   cts:polygon*
Summary:

Create a sequence of cts:polygon values from a polygon element in one of the supported markup vocabularies. These polygons represent the interior polygons, if any.

Parameters:
$polygon : An elements representing the polygon.

Example: 
  xquery version "1.0-ml";
  import module namespace geo = "http://marklogic.com/geospatial"
      at "/MarkLogic/geospatial/geospatial.xqy";
  declare namespace georss= "http://www.georss.org/georss";

  (: Returns empty; no interior polygon in this format :)
  geo:interior-polygon( 
    <georss:polygon>
      12.5,-127.24 15.25,-127.8 13.45,-126.1 12.5,-127.24
    </georss:polygon>
  )
geo:point(
$point as element()
)  as   cts:point
Summary:

Create a cts:point value from an element representing a point in one of the supported markup vocabularies.

Parameters:
$point : An element representing a point.

Example: 
  xquery version "1.0-ml";
  import module namespace geo = "http://marklogic.com/geospatial"
         at "/MarkLogic/geospatial/geospatial.xqy";
  declare namespace gml= "http://www.opengis.net/gml";

  geo:point(<gml:Point><gml:pos>12.5 -127.24</gml:pos></gml:Point>)
geo:polygon(
$points as element()+
)  as   cts:polygon
Summary:

Create a cts:polygon value from a sequence of point elements in one of the supported markup vocabularies.

Parameters:
$points : A sequence of elements, each representing a vertex (point) of the polygon.

Example: 
  xquery version "1.0-ml";
  import module namespace geo = "http://marklogic.com/geospatial"
         at "/MarkLogic/geospatial/geospatial.xqy";

  geo:polygon(( <Dot Latitude="12.5" Longitude="-127.24"/>,
                <Dot Latitude="15.25" Longitude="-127.8"/>,
                <Dot Latitude="13.45" Longitude="-126.1"/>,
                <Dot Latitude="12.5" Longitude="-127.24"/>
             ))
geo:polygon(
$polygon as element()
)  as   cts:polygon
Summary:

Create a cts:polygon value from a polygon element in one of the supported markup vocabularies. This polygon represents the exterior polygon for those vocabularies that include both exterior and interior polygons in their representation.

Parameters:
$polygon : An elements representing the polygon.

Example: 
  xquery version "1.0-ml";
  import module namespace geo = "http://marklogic.com/geospatial"
         at "/MarkLogic/geospatial/geospatial.xqy";
  declare namespace georss= "http://www.georss.org/georss";

  geo:polygon( <georss:polygon>
                12.5,-127.24 15.25,-127.8 13.45,-126.1 12.5,-127.24
               </georss:polygon>
             )
 © Copyright 2002-2011 MarkLogic Corporation.    All rights reserved.