DOCSEARCHbyAlgolia
Submit Docs

tokml

repository·master·Indexed 41 days ago

https://github.com/mapbox/tokml

A utility for converting GeoJSON data into KML (Keyhole Markup Language) format, available as a JavaScript library for Node.js and browser environments or as a standalone command-line tool. Version 0.4.0 supports property mapping for names, descriptions, and timestamps, as well as automatic styling via the simplestyle-spec.

Tokens
1.7K
Snippets
8
Records
10
Agent score
49%

What's inside tokml

  1. Install tokml

    master

    You can install tokml for use in Node.js or browserify environments, or install it globally to use as a command-line binary.

    For Node.js/browserify:

    npm install --save tokml

    As a global binary:

    npm install -g tokml

    Manual download: If you are not using a package manager, you can download the source directly:

    wget https://raw.github.com/mapbox/tokml/master/tokml.js
    npm install --save tokml

  2. Use simplestyle-spec for KML styling

    master

    By setting simplestyle: true in the options, tokml will automatically generate KML <Style> elements based on properties following the simplestyle-spec.

    Supported Marker Styles

    For Point or MultiPoint geometries, the following properties trigger marker styles:

    • marker-color: Hex color (e.g., #ff0000).
    • marker-size: Size (e.g., small, medium, large).
    • marker-symbol: Symbol name.

    Note: Marker icons are served from Mapbox's API (e.g., https://api.tiles.mapbox.com/v3/marker/...).

    Supported Line and Polygon Styles

    For LineString, MultiLineString, Polygon, or MultiPolygon geometries, the following properties trigger styles:

    • stroke: Hex color for the line.
    • stroke-opacity: Opacity (0.0 to 1.0).
    • stroke-width: Width of the line.
    • fill: Hex color for the polygon fill.
    • fill-opacity: Opacity (0.0 to 1.0).

    Example

    const geojson = {
  type: 'Feature',
  geometry: { type: 'Point', coordinates: [0, 0] },
  properties: {
    'marker-color': '#ff0000',
    'marker-size': 'large'
  }
};

const kml = tokml(geojson, { simplestyle: true });

  3. Examples of tokml usage

    master

    Below are common patterns for using tokml with different configuration requirements.

    // Basic conversion: kml is a string of KML data
var kml = tokml(geojsonObject);

// Mapping specific properties to KML name and description
var kmlNameDescription = tokml(geojsonObject, {
    name: 'name',
    description: 'description'
});

// Defining the KML document name and description as a whole
var kmlDocumentName = tokml(geojsonObject, {
    documentName: 'My List Of Markers',
    documentDescription: "One of the many places you are not I am"
});

  5. Configure tokml options

    master

    The options object allows you to map GeoJSON properties to specific KML tags and configure document-level metadata.

    Property Mapping

    Map GeoJSON feature properties to KML's standard name, description, or TimeStamp tags:

    • name: The property name in each GeoJSON Feature to be used as the KML name.
    • description: The property name in each GeoJSON Feature to be used as the KML description.
    • timestamp: The property name in each GeoJSON Feature containing a timestamp in XML Schema Time format (yyyy-mm-ddThh:mm:sszzzzzz).

    Document Metadata

    Set metadata for the entire KML document:

    • documentName: The name of the full KML document.
    • documentDescription: The description of the full KML document.

    Styling

    var kml = tokml(geojsonObject, {
    name: 'name',
    description: 'description',
    timestamp: 'time',
    documentName: 'My List Of Markers',
    documentDescription: 'Description text',
    simplestyle: true
});

  6. Use tokml as a CLI binary

    master

    Once installed globally, you can convert GeoJSON files to KML via the command line. You can either pass a filename as an argument or pipe the GeoJSON data into the command.

    Convert from a file:

    tokml file.geojson > file.kml

    Convert via stdin:

    tokml < file.geojson > file.kml
    tokml file.geojson > file.kml

  7. Convert GeoJSON to KML with tokml()

    master

    The tokml function converts GeoJSON objects (FeatureCollection, Feature, or Geometry) into a KML string. It supports optional property mapping for names, descriptions, and timestamps, as well as automatic styling via the simplestyle option.

    Usage

    const tokml = require('tokml');

const geojson = {
  type: 'Feature',
  geometry: {
    type: 'Point',
    coordinates: [0, 0]
  },
  properties: {
    name: 'My Point',
    description: 'A sample point'
  }
};

const kml = tokml(geojson);

  9. Reference: Supported GeoJSON Geometry Types

    master

    The tokml library supports the following GeoJSON geometry types and maps them to their KML equivalents:

    GeoJSON TypeKML Element
    Point<Point>
    LineString<LineString>
    Polygon<Polygon> (supports outerBoundaryIs and innerBoundaryIs)
    MultiPoint<MultiGeometry> containing <Point> elements
    MultiLineString<MultiGeometry> containing <LineString> elements
    MultiPolygon<MultiGeometry> containing <Polygon> elements
    GeometryCollection<MultiGeometry> containing the constituent geometries

    Note: Styling for GeometryCollection and MultiGeometry is not supported.

  10. Use the tokml CLI to convert GeoJSON to KML

    master

    The tokml CLI tool converts GeoJSON data into KML format. You can provide a GeoJSON file as a command-line argument or pipe GeoJSON data directly into the command via stdin. The output is written to stdout.

    Usage

    From a file:

    tokml input.geojson

    From stdin (piping):

    cat input.geojson | tokml

    Options

    • --simplestyle (boolean): Enables simplestyle mode during conversion.

    If you run the command without arguments and without piping data, the tool will display a help message.

    tokml input.geojson
# or
cat input.geojson | tokml