Cómo añadir datos personalizados

KML ofrece tres formas para añadir datos personalizados a un recurso (Feature) KML. La elección dependerá del tipo de datos que vayas a añadir, así como de la forma en que se vayan a utilizar los datos en la presentación KML. Concretamente, el elemento de datos ampliados (<ExtendedData>) proporciona los siguientes mecanismos:

  • Elemento de datos (<Data>): permite añadir pares de nombre/valor sin tipos definidos a los datos de usuario asociados mediante un determinado recurso (NetworkLink, Placemark, GroundOverlay, PhotoOverlay, ScreenOverlay, Document o Folder). La viñeta muestra estos pares nombre/valor de forma predeterminada. Esta información también se puede utilizar para sustituir la entidad en el elemento de texto (<text>) del elemento del estilo de viñeta (<BalloonStyle>). Consulta la sección acerca sobre el uso del elemento de estilo de viñeta (BalloonStyle) como plantilla.
  • Elementos de esquema (<Schema>) y de datos de esquema (<SchemaData>): permiten añadir datos con tipos definidos a los datos de usuario asociados a un determinado recurso.
  • Datos XML arbitrarios: permiten conservar los datos de usuario en un archivo KML. Google Earth transmite estos datos junto con el archivo y los guarda, aunque no los utiliza.

Nota: Estos tres mecanismos se pueden combinar en el mismo archivo. Si vas a añadir diferentes tipos de datos procedentes de distintas fuentes, sería buena idea que para algunos datos personalizados, utilizaras el sistema de datos con tipos definidos (Schema/SchemaData) y datos sin tipos definidos (Data) para el resto de datos personalizados.

¿Qué sistema debes utilizar?

En la mayoría de los casos, el elemento <Data> ofrece el mecanismo más sencillo y efectivo para añadir datos sin tipos definidos a un recurso KML. Este método es relativamente fácil de implementar y ofrece la ventaja de facilitar el uso de una plantilla BalloonStyle, que se puede aplicar a todos los elementos Placemark de un archivo KML. Consulta la sección Sustitución de entidades para elementos de datos ampliados para ver un ejemplo de este uso.

Los elementos <Schema> y <SchemaData> permiten añadir datos de usuarios con tipos definidos. Estos elementos se ofrecen principalmente a los usuarios con datos GIS (siglas en inglés de sistema de información geográfica). Si dispones de datos con tipos definidos en uso por una aplicación informática externa, probablemente tengas que utilizar los elementos <Schema> y <SchemaData> para añadir tipos de datos estructurados a un recurso (Google Earth no utiliza este tipo de información, aunque puede que las demás aplicaciones sí la necesiten). Probablemente, los usuarios ocasionales no tengan necesidad de conocer los aspectos más técnicos de este mecanismo. Al igual que el elemento <Data>, el elemento <SchemaData> ofrece el uso de plantillas BalloonStyle.

Si lo único que necesitas es transmitir datos junto con un archivo KML y no necesitas que Google Earth los procese, utiliza el recurso de datos XML arbitrarios, que te permitirá referenciar un prefijo de espacio de nombres KML en el contexto KML actual. Para obtener más información, consulta la sección acerca de los datos XML arbitrarios.

Cómo añadir pares de nombre/valor sin tipos definidos

El elemento <Data> es un mecanismo sencillo y eficaz para añadir pares de nombre/valor sin tipos definidos a un recurso KML. La sintaxis para este elemento es la siguiente:

<ExtendedData>                       
 <Data name="string">
  <displayName>...</displayName>    <!-- string -->
    <value>...</value>                <!-- string -->
 </Data> </ExtendedData>

El atributo de nombre (name) es un ID único para esta parte de los datos. El elemento de nombre para mostrar (<displayName>) se utiliza cuando se quiere mostrar el nombre de estos datos de un modo fácil de comprender para el usuario. El elemento <displayName> puede incluir CDATA con espacios, direcciones URL e hiperenlaces.

A continuación se ofrece un ejemplo de marca de posición (Placemark) con datos personalizados sobre varios hoyos en un campo de golf:

<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
  <name>Ejemplo de mi club de golf</name>
  <Placemark>
    <name>Club de golf</name>
    <ExtendedData>
      <Data name="holeNumber">
        <value>1</value>
      </Data>
      <Data name="holeYardage">
        <value>234</value>
      </Data>
      <Data name="holePar">
        <value>4</value>
      </Data>
    </ExtendedData>
    <Point>
      <coordinates>-111.956,33.5043</coordinates>
    </Point>
 </Placemark> <Placemark> <name>By the lake</name> <ExtendedData> <Data name="holeNumber"> <value>5</value> </Data> <Data name="holeYardage"> <value>523</value> </Data> <Data name="holePar"> <value>5</value> </Data> </ExtendedData> <Point> <coordinates>-111.95,33.5024</coordinates> </Point>
 </Placemark> </Document> </kml>

En esta captura de pantalla se ve cómo se muestran los elementos <Data> de forma predeterminada en una tabla de la viñeta del elemento Placemark.

Ejemplo de elementos <Data> con el estilo predeterminado de la viñeta

Repaso: cómo utilizar el elemento estilo de viñeta (BallonStyle) como una plantilla

En KML, se puede definir un estilo (Style) una vez y asignarle un ID. Después de definir el estilo de esta forma, puedes hacer referencia a dicho estilo varias veces mediante el archivo KML (o en otros archivos KML), a través del elemento de URL de estilo (<styleUrl>). Al estilo definido de esta forma se le denomina estilo compartido. El elemento <text> de un elemento <BalloonStyle> admite la sustitución de entidades. Los valores individuales se pueden sustituir según la instancia de la entidad. Las entidades estándar que se pueden sustituir son las siguientes:

$[name]
Se sustituye por el nombre de la marca de posición.
$[description]
Se sustituye por la descripción de la marca de posición.
$[address]
Se sustituye por la dirección de la marca de posición.
$[id]
Se sustituye por el ID de la marca de posición.
$[Snippet]
Se sustituye por el fragmento de la marca de posición.
$[geDirections]
Se sustituye por las indicaciones para llegar en coche hasta/desde la marca de posición.

Sustitución de entidades para elementos de datos ampliados

Google Earth también admite sustituir entidades de ciertos elementos de datos ampliados en el elemento <text> del elemento <BalloonStyle>. En el elemento <text>, se puede hacer referencia a las siguientes entidades:

Variable Se sustituye por Ejemplo
$[name_attribute_of_Data_element] Contenido del elemento de valor (<value>) Número de hoyo, distancia del hoyo
$[name_attribute_of_Data/displayName] Contenido del elemento de nombre para mostrar (<displayName>) Número de hoyo, distancia del hoyo

En este ejemplo se crea una plantilla <BalloonStyle> para el ejemplo de campo de golf. En cada viñeta del elemento Placemark, Google Earth sustituye el nombre de este elemento y, a continuación, escribe la información correspondiente al número de hoyo, el par y la distancia de cada uno de los hoyos: 

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
  <name>Data+BalloonStyle</name>
  <Style id="golf-balloon-style">
    <BalloonStyle>
      <text>
        <![CDATA[
          This is $[name]
          This is hole $[holeNumber]
          The par for this hole is $[holePar]
          The yardage is $[holeYardage]
        ]]>
      </text>
    </BalloonStyle>
  </Style>
  <!-- Shared style sample
        Two Placemarks use the same balloon template
  -->
  <Placemark>
    <name>Club house</name>
    <styleUrl>#golf-balloon-style</styleUrl>
    <ExtendedData>
      <Data name="holeNumber">
        <value>1</value>
      </Data>
      <Data name="holeYardage">
        <value>234</value>
      </Data>
      <Data name="holePar">
        <value>4</value>
      </Data>
    </ExtendedData>
    <Point>
      <coordinates>-111.956,33.5043</coordinates>
    </Point>
  </Placemark>
  <Placemark>
    <name>By the lake</name>
    <styleUrl>#golf-balloon-style</styleUrl>
    <ExtendedData>
      <Data name="holeNumber">
        <value>5</value>
      </Data>
      <Data name="holeYardage">
        <value>523</value>
      </Data>
      <Data name="holePar">
        <value>5</value>
      </Data>
    </ExtendedData>
    <Point>
      <coordinates>-111.95,33.5024</coordinates>
    </Point>
  </Placemark>
</Document>
</kml>

Esta es una captura de pantalla del ejemplo:

Ejemplo de elementos <Data> con el estilo predeterminado de la viñeta

A continuación se ofrece un ejemplo más realista de cómo se utilizaría el elemento <displayName>. Esta técnica se presta a la localización del texto y a la aplicación de un formato más elaborado.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
 <Document>
 <name>Entity-Replacement</name>
 <Style id="displayName-value">
 <BalloonStyle>
 <text>
 <![CDATA[
 This is $[name]<br/>
 $[holeNumber/displayName] $[holeNumber]<br/>
 $[holePar/displayName] $[holePar]<br/>
 $[holeYardage/displayName] $[holeYardage]
 ]]>
 </text>
 </BalloonStyle>
 </Style>
 <!-- Shared style sample
 Two Placemarks use the same balloon template
 -->
 <Placemark>
 <name>Club house</name>
 <styleUrl>#displayName-value</styleUrl>
 <ExtendedData>
 <Data name="holeNumber">
 <displayName><![CDATA[
 <b>This is hole </b>
 ]]></displayName>
 <value>1</value>
 </Data>
 <Data name="holePar">
 <displayName><![CDATA[
 <i>The par for this hole is </i>
 ]]></displayName>
 <value>4</value>
 </Data>
 <Data name="holeYardage">
 <displayName><![CDATA[
 <b><i>The yardage is </i></b>
 ]]></displayName>
 <value>234</value>
 </Data>
 </ExtendedData>
 <Point>
 <coordinates>-111.956,33.5043</coordinates>
 </Point>
 </Placemark>
 <Placemark>
 <name>By the lake</name>
 <styleUrl>#Entity-Replacement</styleUrl>
 <ExtendedData>
 <Data name="holeNumber">
 <displayName><![CDATA[
 <b>This is hole </b>
 ]]></displayName>
 <value>5</value>
 </Data>
 <Data name="holePar">
 <displayName><![CDATA[
 <i>The par for this hole is </i>
 ]]></displayName>
 <value>5</value>
 </Data>
 <Data name="holeYardage">
 <displayName><![CDATA[
 <b><i>The yardage is </i></b>
 ]]></displayName>
 <value>523</value>
 </Data>
 </ExtendedData>
 <Point>
 <coordinates>-111.95,33.5024</coordinates>
 </Point>
 </Placemark>
 </Document>
</kml>

Este es un ejemplo de viñeta con esta plantilla de estilo de viñeta:

Cómo añadir datos con tipos definidos a un recurso

Los elementos <Schema> y <SchemaData> permiten añadir datos con tipos definidos a un recurso. Algunas aplicaciones de programación y GIS requieren este recurso porque manejan datos con tipos definidos.

Aspectos generales sobre cómo añadir datos con tipos definidos

Para añadir un tipo personalizado a un recurso KML, tienes que llevar a cabo dos tareas básicas:

  1. Crea un elemento <Schema>, que indicará el nuevo tipo.
  2. Crea instancias para el nuevo tipo mediante el elemento <SchemaData>.

Cómo declarar el elemento Schema

El elemento <Schema> indica un tipo estructurado y siempre es un elemento secundario del elemento de documento (<Document>). Un elemento Document puede incluir varios elementos Schema o ninguno.

El atributo ID

El elemento <Schema> siempre tiene un atributo ID, al que se hace referencia cuando se crean las instancias de este tipo (mediante <SchemaData>). Este ID debe ser único dentro del archivo KML.

El atributo de nombre (name)

El atributo name que se utiliza para la sustitución de entidades, es opcional.

Sintaxis

El elemento Schema presenta la siguiente sintaxis:

<Schema name="string" id="ID">   
  <SimpleField type="string" name="string">     
    <displayName>...</displayName>            <!-- string -->   
  </SimpleField> 
</Schema>

Un campo sencillo (<SimpleField>) siempre posee los atributos de nombre (name) y de tipo (type) y, si no posee ambos, dicho campo se ignorará. El atributo de nombre se utiliza para sustituir entidades en el elemento <text> del elemento <BalloonStyle>. El tipo Simplefield puede ser uno de los siguientes:

  • string
  • int
  • uint
  • short
  • ushort
  • float
  • double
  • bool

Cómo definir cada instancia de los datos

Utiliza el elemento <SchemaData> para crear una instancia del tipo definido por el usuario. La sintaxis del elemento <SchemaData> es la siguiente:

<ExtendedData>                   
  <SchemaData schemaUrl="anyURI">
    <SimpleData name=""> ... </SimpleData>       <!-- string -->
  </SchemaData>
</ExtendedData>

El atributo de URL de esquema (schemaUrl) hace referencia al ID del esquema que indica el tipo (al igual que la URL de estilo [styleUrl] hace referencia al ID de un estilo que ya se ha indicado).Si la URL de esquema (schemaUrl) es una dirección http, Google Earth volverá a extraer este archivo de la red. Solo puede haber una instancia de un tipo definido por el usuario por cada elemento Placemark.

Ejemplo

El siguiente ejemplo declara un tipo definido por el usuario denominado vista panorámica (ScenicVista). Este tipo contiene tres campos: el nombre y la longitud del sendero (TrailHeadName, TrailLength) y el aumento de la elevación (ElevationGain). El campo TrailHeadName contiene valores del tipo string. El campo TrailLength contiene valores del tipo double. El campo ElevationGain contiene valores del tipo int. El elemento Placemark denominado sendero sencillo (Easy trail) contiene una instancia de este usuario. Esta instancia tiene un valor de "Pi en el cielo" para el campo TrailHeadName, un valor de 3,14159 para el campo TrailLength y un valor de 10 para el campo ElevationGain.

<kml xmlns="http://www.opengis.net/kml/2.2"> 
<Document>   
  <name>ExtendedData+SchemaData</name>   
  <open>1</open>

  <!-- Declare the type "TrailHeadType" with 3 fields -->
  <Schema name="TrailHeadType" id="TrailHeadTypeId">     
    <SimpleField type="string" name="TrailHeadName">       
      <displayName><![CDATA[<b>Trail Head Name</b>]]></displayName>     
    </SimpleField>     
    <SimpleField type="double" name="TrailLength">       
      <displayName><![CDATA[<i>Length in miles</i>]]></displayName>     
    </SimpleField>     
    <SimpleField type="int" name="ElevationGain">       
      <displayName><![CDATA[<i>Change in altitude</i>]]></displayName>     
    </SimpleField>   
  </Schema> 

<!-- This is analogous to adding three fields to a new element of type TrailHead:

  <TrailHeadType>        
    <TrailHeadName>...</TrailHeadName>        
    <TrailLength>...</TrailLength>        
    <ElevationGain>...</ElevationGain>    
 </TrailHeadType>
--> <!-- Instantiate some Placemarks extended with TrailHeadType fields --> <Placemark> <name>Easy trail</name> <ExtendedData> <SchemaData schemaUrl="#TrailHeadTypeId">  <SimpleData name="TrailHeadName">Pi in the sky</SimpleData> <SimpleData name="TrailLength">3.14159</SimpleData> <SimpleData name="ElevationGain">10</SimpleData> </SchemaData>  </ExtendedData> <Point> <coordinates>-122.000,37.002</coordinates> </Point> </Placemark> <Placemark> <name>Difficult trail</name> <ExtendedData> <SchemaData schemaUrl="#TrailHeadTypeId">  <SimpleData name="TrailHeadName">Mount Everest</SimpleData> <SimpleData name="TrailLength">347.45</SimpleData> <SimpleData name="ElevationGain">10000</SimpleData> </SchemaData> </ExtendedData> <Point> <coordinates>-121.998,37.0078</coordinates> </Point> </Placemark> </Document> </kml>

Ejemplo del elemento SchemaData con estilo predeterminado de la viñeta

Cómo sustituir entidades en el nombre para mostrar (displayName)

El mecanismo Schema/SchemaData también admite la sustitución de entidades en el elemento <text> del elemento de estilo de viñeta <BalloonStyle>.

El elemento <displayName> del elemento <Schema> permite ofrecer una versión más fácil de utilizar para el usuario de un tipo de datos personalizados. Si se cambia una vez la cadena de comandos del elemento <Schema>, se cambiará el elemento <displayName> de todos los recursos incluidos en dicho tipo.

En el elemento <text> del elemento <BalloonStyle>, se utiliza la siguiente sintaxis para cualificar el elemento <displayName>:

$[TYPENAME/TYPEFIELD/displayName]

donde

TYPENAME
Es el atributo de nombre (name) del elemento <Schema>
TYPEFIELD
Es el atributo de nombre (name) del elemento <SimpleField>.
displayName
Es el elemento de nombre para mostrar (<displayName>) del elemento <SimpleField>.

El siguiente código añade una plantilla BalloonStyle al ejemplo anterior del elemento SchemaData. Al igual que en el ejemplo anterior del campo de golf, la plantilla se crea mediante los elementos <Style>, <BallonStyle> y <text> al principio del documento (Document). Cada elemento Placemark del archivo hace referencia a esta plantilla de estilo, denominada "ExtendedData+SchemaData". 

<kml xmlns="http://www.opengis.net/kml/2.2"> 
<Document>   
  <name>ExtendedData+SchemaData</name>   
  <open>1</open>    
  <!-- Create a balloon template referring to the user-defined type -->
  <Style id="trailhead-balloon-template">     
    <BalloonStyle>       
      <text>
        <![CDATA[         
          <h2>My favorite trails!</h2>         
          <br/><br/>         
          The $[TrailHeadType/TrailHeadName/displayName] is <i>$[TrailHeadType/TrailHeadName]</i>.        
          The trail is $[TrailHeadType/TrailLength] miles.         <br/>        
          The climb is $[TrailHeadType/ElevationGain] meters.         <br/><br/>       
        ]]>
      </text>     
    </BalloonStyle>
  </Style>     

  <!-- Declare the type "TrailHeadType" with 3 fields -->
  <Schema name="TrailHeadType" id="TrailHeadTypeId">     
    <SimpleField type="string" name="TrailHeadName">       
      <displayName><![CDATA[<b>Trail Head Name</b>]]></displayName>     
    </SimpleField>     
    <SimpleField type="double" name="TrailLength">       
      <displayName><![CDATA[<i>The length in miles</i>]]></displayName>     
    </SimpleField>     
    <SimpleField type="int" name="ElevationGain">       
      <displayName><![CDATA[<i>change in altitude</i>]]></displayName>     
    </SimpleField>   
  </Schema>       

  <!-- Instantiate some Placemarks extended with TrailHeadType fields -->    
  <Placemark>     
    <name>Easy trail</name>     
    <styleUrl>#trailhead-balloon-template</styleUrl>     
    <ExtendedData>       
      <SchemaData schemaUrl="#TrailHeadTypeId">        
        <SimpleData name="TrailHeadName">Pi in the sky</SimpleData>         
        <SimpleData name="TrailLength">3.14159</SimpleData>         
        <SimpleData name="ElevationGain">10</SimpleData>       
      </SchemaData>     
    </ExtendedData>     
    <Point>       
      <coordinates>-122.000,37.002</coordinates>     
    </Point>   
  </Placemark>    
  <Placemark>     
    <name>Difficult trail</name>     
    <styleUrl>#trailhead-balloon-template</styleUrl>     
    <ExtendedData>
      <SchemaData schemaUrl="#TrailHeadTypeId">         
        <SimpleData name="TrailHeadName">Mount Everest</SimpleData>        
        <SimpleData name="TrailLength">347.45</SimpleData>         
        <SimpleData name="ElevationGain">10000</SimpleData>       
      </SchemaData>    
    </ExtendedData>    
    <Point>       
      <coordinates>-121.998,37.0078</coordinates>     
    </Point>   
  </Placemark>   
</Document> 
</kml>

Ejemplo del elemento SchemaData con una plantilla BalloonStyle

Compara la viñeta creada mediante una plantilla BalloonStyle con el estilo de viñeta predeterminado de los mismos datos que aparecen en la captura de pantalla anterior.

Cómo añadir datos XML arbitrarios a un recurso

La forma más sencilla de añadir datos a un recurso es añadirlos directamente como un valor de datos añadidos (<ExtendedData>). Google Earth conserva dichos datos, pero no los procesa.

Los elementos de datos personalizados añadidos de esta forma tienen que incluir un prefijo de espacio de nombres (xmlns:prefix="namespace"). Este prefijo se puede añadir al elemento <kml> o al elemento de datos extendidos (<ExtendedData>). El prefijo de espacio de nombres externo debe cualificar cada una de las instancias de los datos del usuario, como aparece en el siguiente ejemplo: 

<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
  <name>ExtendedData Test</name>
  <Placemark>
    <name>CampsiteData</name>
    <!-- Imported schema requires use of namespace prefix -->
    <ExtendedData xmlns:camp="http://campsites.com">
      <camp:number>14</camp:number>
      <camp:parkingSpaces>2</camp:parkingSpaces>
      <camp:tentSites>4</camp:tentSites>
    </ExtendedData>
    <Point>
      <coordinates>-114.041,53.7199</coordinates>
    </Point>
  </Placemark>
</Document>
</kml>

Volver al principio