GET Export Report KML Format

Abstract

Description of the KML export format of the GET Export Report API.


Table of Contents

The KML format writes KML to the HTTP response body.

It is required to specify both the <kml> configuration element and the base table primaryKeyColumns attribute to activate the kml format.

Format Parameter:  kml

Response Content-Type:  application/vnd.google-earth.kml+xml

Response Content-Disposition:  The Content-Disposition HTTP header is set to the value of the <report> name attribute with the underscore character (_) substituted for any space, comma, or semicolon character plus the .kml extension.

Pull Reports™ Standard Edition Format

This format is only available under the Pull Reports™ Standard Edition license. To evaluate this format with a Pull Reports™ Community Edition license, enable evaluation mode.

Geometry configured via <kml> The geometry value of each KML <Placemark> (such as a <Point>, <LineString> , or <Polygon>) is the value of the base table column designated by the <report>'s <kml> geometryColumnPath attribute. The KML export format will only create a <Placemark> for result rows with a non-null value for the column referenced by geometryColumnPath.

If no <kml> geometryColumnPath is designated, the format will return a 400 HTTP response status.

Geometry distinctness respective to base table columns primary key columns:  The kml format will create a single KML geometry per distinct result row. Distinctness is determined from the base table primaryKeyColumns attribute.

Value of <Document> <name> For OK responses, the KML <Document> <name> value is:

Export from: [<catalog> name]:[<report> name] [filters applied]

The "filters applied" text is only appended if at least one filter parameter is specified in the Export Report REST API request.

For Error responses, the KML <Document> <name> value is:

Error in Export. See description.

Value of <Document> <description> For OK responses, if at least one filter parameter is specified, the <description> contains a bulleted list of human readable filter definitions. Additionally, the <description> contains a bulleted list of subquery descriptions if at least one <subquery>'s parent <table> is included within the export result and the <subquery> has a non-null description.

For Error responses, the <description> contains a bulleted list of error messages.

Additional columns as <ExtendedData> Each base table column of the export result row is included as a child <Data> element of the <Placemark>'s <ExtendedData> element. Each <Data>'s name attribute is the corresponding <column>'s column resource path. Each <Data>'s child <displayName> and <value> elements contain the <column>'s displayName and result row value respectively.

Any <column>s with a <url_template> have their values surrounded with an HTML anchor tag (a) with the filled URL template as the value of the href attribute.

Customizing <Placemark> <name>s:  By default, the <name> element of each <Placemark> is the name of the <report> plus the word "Geometry". Specify the <report>'s <placemark_name_template> element to customize the <name> element based on values from the result row.

OK Response

Status Code: 200

KML responses without error follow this example:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
    <name>Export from: Class Information:Student Report &lt;i&gt;filters applied&lt;/i&gt;</name>
    <!-- Human readable filter definitions are only included in the <description>
         if at least one filter parameter is specified. Otherwise the <description>
         is empty. -->
    <description><![CDATA[<h5>Filters</h5><ul>
        <li>'Student', 'First Name' like 'J%'</li>
        <li>'Student', 'Last Name' = 'Hernandez'</li>
    </ul>
    <h5>Subqueries</h5>
    <ul>
        <li>'Student': Rows are restricted to those students within your school.</li>
    </ul>]]></description> 
    <Placemark>
      <!-- In this example, the <Placemark> <name> is customized via:
      <placemark_name_template>${@fname} ${@lname} Home</placemark_name_template> -->
      <name>Joe Hernandez Home</name>
      <ExtendedData>
        <Data name="/student@id">
          <displayName>Student ID</displayName>
          <value>177</value>
        </Data>
        <Data name="/student@fname">
          <displayName>First Name</displayName>
          <value>Joe</value>
        </Data>
        <Data name="/student@lname">
          <displayName>Last Name</displayName>
          <value>&lt;a href="/some/url/177"&gt;Hernandez&lt;/a&gt;</value>
        </Data>
      </ExtendedData>
      <!-- The geometry value is the value of the base table column specified by
           <kml geometryColumnPath="..."> -->
      <Point>
        <coordinates>-105.0906227,40.5656519,0</coordinates>
      </Point>
    </Placemark>
    <Placemark>
      <name>Julia Hernandez Home</name>
      <ExtendedData>
        <Data name="/student@id">
          <displayName>Student ID</displayName>
          <value>213</value>
        </Data>
        <Data name="/student@fname">
          <displayName>First Name</displayName>
          <value>Julia</value>
        </Data>
        <Data name="/student@lname">
          <displayName>Last Name</displayName>
          <value>&lt;a href="/some/url/213"&gt;Hernandez&lt;/a&gt;</value>
        </Data>
      </ExtendedData>
      <Point>
        <coordinates>-105.0994311,40.5673064,0</coordinates>
      </Point>
    </Placemark>
  </Document>
  </kml>

Error Response

Status Code: 400 and 500

KML responses with error follow this example:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
    <name>Error in Export. See description.</name>
    <description><![CDATA[
    <ul>
        <li>The filter "/student@id & 173" does not match filter grammar. The "Operator" definition is missing or unparseable.</li>
    </ul>
    ]]></description>
  </Document>
</kml>