Description of the KML export format of the GET Export Report API.
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.
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.
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 <i>filters applied</i></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><a href="/some/url/177">Hernandez</a></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><a href="/some/url/213">Hernandez</a></value> </Data> </ExtendedData> <Point> <coordinates>-105.0994311,40.5673064,0</coordinates> </Point> </Placemark> </Document> </kml>
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>