mapshaper 0.6.121 → 0.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -3
- package/mapshaper.js +1342 -275
- package/package.json +5 -2
- package/www/assets/jetbrains-mono-regular.woff2 +0 -0
- package/www/assets/static-page.css +179 -0
- package/www/docs/_assets/cmd-search.js +213 -0
- package/www/docs/_assets/docs.css +712 -0
- package/www/docs/_assets/docs.js +75 -0
- package/www/docs/_assets/highlight.css +10 -0
- package/www/docs/essentials/command-line.html +127 -0
- package/www/docs/essentials/command-line.html.md +112 -0
- package/www/docs/essentials/web-app.html +138 -0
- package/www/docs/essentials/web-app.html.md +106 -0
- package/www/docs/examples/basics.html +276 -0
- package/www/docs/examples/basics.html.md +371 -0
- package/www/docs/examples/data/Makefile +31 -0
- package/www/docs/examples/data/globe.msx +0 -0
- package/www/docs/examples/data/globe.svg +616 -0
- package/www/docs/examples/data/globe.txt +21 -0
- package/www/docs/examples/data/globe.zip +0 -0
- package/www/docs/examples/data/ne_50m_admin_0_countries.geojson +1 -0
- package/www/docs/examples/data/ne_50m_admin_1_states_provinces_lakes.geojson +1 -0
- package/www/docs/examples/data/us-states.msx +0 -0
- package/www/docs/examples/data/us-states.svg +56 -0
- package/www/docs/examples/data/us-states.txt +6 -0
- package/www/docs/examples/data/us-states.zip +0 -0
- package/www/docs/examples/globe.html +108 -0
- package/www/docs/examples/globe.html.md +64 -0
- package/www/docs/examples/us-states.html +88 -0
- package/www/docs/examples/us-states.html.md +44 -0
- package/www/docs/formats/csv.html +127 -0
- package/www/docs/formats/csv.html.md +97 -0
- package/www/docs/formats/dbf.html +87 -0
- package/www/docs/formats/dbf.html.md +39 -0
- package/www/docs/formats/flatgeobuf.html +86 -0
- package/www/docs/formats/flatgeobuf.html.md +42 -0
- package/www/docs/formats/geojson.html +107 -0
- package/www/docs/formats/geojson.html.md +65 -0
- package/www/docs/formats/geopackage.html +87 -0
- package/www/docs/formats/geopackage.html.md +42 -0
- package/www/docs/formats/json.html +83 -0
- package/www/docs/formats/json.html.md +35 -0
- package/www/docs/formats/kml.html +82 -0
- package/www/docs/formats/kml.html.md +39 -0
- package/www/docs/formats/overview.html +192 -0
- package/www/docs/formats/overview.html.md +35 -0
- package/www/docs/formats/shapefile.html +123 -0
- package/www/docs/formats/shapefile.html.md +84 -0
- package/www/docs/formats/snapshot.html +87 -0
- package/www/docs/formats/snapshot.html.md +39 -0
- package/www/docs/formats/svg.html +99 -0
- package/www/docs/formats/svg.html.md +51 -0
- package/www/docs/formats/topojson.html +102 -0
- package/www/docs/formats/topojson.html.md +54 -0
- package/www/docs/gallery/index.html +80 -0
- package/www/docs/gallery/index.html.md +29 -0
- package/www/docs/guides/combining-layers.html +105 -0
- package/www/docs/guides/combining-layers.html.md +81 -0
- package/www/docs/guides/expressions.html +600 -0
- package/www/docs/guides/expressions.html.md +376 -0
- package/www/docs/guides/programmatic.html +117 -0
- package/www/docs/guides/programmatic.html.md +91 -0
- package/www/docs/guides/projections.html +158 -0
- package/www/docs/guides/projections.html.md +118 -0
- package/www/docs/guides/simplification.html +110 -0
- package/www/docs/guides/simplification.html.md +94 -0
- package/www/docs/guides/topology.html +90 -0
- package/www/docs/guides/topology.html.md +63 -0
- package/www/docs/images/simplification-detail.png +0 -0
- package/www/docs/images/simplification-dp.png +0 -0
- package/www/docs/images/simplification-mod2.png +0 -0
- package/www/docs/index.html +101 -0
- package/www/docs/index.html.md +59 -0
- package/www/docs/reference.html +1302 -0
- package/www/docs/reference.html.md +1817 -0
- package/www/docs/whats-new.html +76 -0
- package/www/docs/whats-new.html.md +53 -0
- package/www/index.html +30 -3
- package/www/llms-full.txt +4040 -0
- package/www/llms.txt +55 -0
- package/www/mapshaper-gui.js +7 -1
- package/www/mapshaper.js +1342 -275
- package/www/page.css +1 -1
- package/www/privacy.html +1 -112
- package/www/sponsor.html +4 -164
- package/www/terms.html +1 -112
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: FlatGeobuf
|
|
3
|
+
description: How Mapshaper reads and writes FlatGeobuf (.fgb), a streamable binary vector format.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# FlatGeobuf
|
|
7
|
+
|
|
8
|
+
FlatGeobuf is a modern binary vector format designed for fast streaming reads. A single self-contained file with UTF-8 text encoding, it avoids the companion-file clutter of Shapefile. Its optional embedded spatial index enables efficient bounding-box queries without reading the whole file, making it well-suited to large datasets served over HTTP. It also works well as a general-purpose GIS exchange format.
|
|
9
|
+
|
|
10
|
+
**File extension:** `.fgb` · **Read:** ✓ · **Write:** ✓ · **Multi-layer:** no (one layer per file)
|
|
11
|
+
|
|
12
|
+
### CLI examples
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
mapshaper buildings.fgb -info
|
|
16
|
+
mapshaper buildings.fgb -simplify 5% -o buildings.geojson
|
|
17
|
+
mapshaper provinces.shp -o provinces.fgb
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
### Format-specific input options
|
|
21
|
+
|
|
22
|
+
There are no FlatGeobuf-specific `-i` options.
|
|
23
|
+
|
|
24
|
+
### Format-specific output options
|
|
25
|
+
|
|
26
|
+
There are no FlatGeobuf-specific `-o` options. The format honors the general flags (`precision=`, `gzip`, `zip`, etc.) where they apply.
|
|
27
|
+
|
|
28
|
+
### Practical notes
|
|
29
|
+
|
|
30
|
+
- FlatGeobuf is single-layer per file. Use [GeoPackage](/docs/formats/geopackage.html.md) or [TopoJSON](/docs/formats/topojson.html.md) when you need to package multiple layers in one file.
|
|
31
|
+
- Mapshaper reads CRS metadata from the file header when it's encoded as an EPSG code. WKT2-only definitions can't be parsed and produce an "Unable to import WKT2 CRS from FlatGeobuf" warning — the layer comes in without a CRS.
|
|
32
|
+
- On output, Mapshaper embeds an EPSG code in the FlatGeobuf header whenever it can derive one from the source: a round-tripped FlatGeobuf or GeoPackage CRS, an `epsg:NNNN` string passed to `-proj`, an `AUTHORITY["EPSG", N]` clause in a Shapefile `.prj`, or any encoding of WGS-84 or Web Mercator (which covers most GeoJSON, CSV-with-lat/lon and `-proj wgs84`/`-proj webmercator` outputs).
|
|
33
|
+
- Mapshaper cannot yet convert an arbitrary proj4 definition (such as a custom Albers projection set with `-proj +proj=aea ...`) to an EPSG code. In that case the file is written with no CRS in the header and a warning is printed: *"Wrote `foo.fgb` without a CRS in the FlatGeobuf header..."*. Re-run the file through `ogr2ogr` if you need the CRS embedded for downstream tools.
|
|
34
|
+
- Mapshaper does not write the optional packed R-tree spatial index, and it doesn't use the index for selective reads of indexed input either — the whole file is read into memory. If you need an indexed `.fgb` for HTTP range-request reads, build it with `ogr2ogr` or the [`flatgeobuf` CLI](https://github.com/flatgeobuf/flatgeobuf).
|
|
35
|
+
|
|
36
|
+
## External resources
|
|
37
|
+
|
|
38
|
+
- [flatgeobuf.org](https://flatgeobuf.org/) — project home with spec links and language bindings.
|
|
39
|
+
- [Kicking the Tires: FlatGeobuf](https://worace.works/2022/02/23/kicking-the-tires-flatgeobuf/) — an independent practical writeup with benchmarks against Shapefile, GeoJSON and GeoPackage.
|
|
40
|
+
- [Bryce Mecum: Flatgeobuf](https://brycemecum.com/2022/04/04/flatgeobuf/) — a hands-on exploration of streaming reads in the browser, including a worth-knowing gotcha about the spatial index sitting at the front of the file.
|
|
41
|
+
- [Cloud-Native Geospatial Formats Guide: FlatGeobuf](https://guide.cloudnativegeo.org/flatgeobuf/) — how the format fits into modern cloud-storage workflows.
|
|
42
|
+
- FlatGeobuf reading and writing in Mapshaper is built on the official [`flatgeobuf`](https://github.com/flatgeobuf/flatgeobuf) JavaScript library, which provides the FlatBuffers schema, header parsing and feature serialisation primitives.
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
<!DOCTYPE html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="UTF-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
+
<title>GeoJSON · mapshaper docs</title>
|
|
7
|
+
<meta name="description" content="How Mapshaper reads and writes GeoJSON, including precision, ndjson and RFC 7946 options.">
|
|
8
|
+
<link rel="icon" type="image/png" href="/images/icon.png">
|
|
9
|
+
<link rel="stylesheet" href="/docs/_assets/highlight.css">
|
|
10
|
+
<link rel="stylesheet" href="/docs/_assets/docs.css">
|
|
11
|
+
</head>
|
|
12
|
+
<body class="">
|
|
13
|
+
|
|
14
|
+
<header class="page-header">
|
|
15
|
+
<a href="/" class="mapshaper-logo">map<span class="logo-highlight">shaper</span></a>
|
|
16
|
+
<span class="header-section-label">Docs</span>
|
|
17
|
+
<nav class="header-nav">
|
|
18
|
+
<a href="/">Web app</a>
|
|
19
|
+
<a href="https://github.com/mbloch/mapshaper">GitHub</a>
|
|
20
|
+
<a href="/sponsor.html" class="sponsor-link"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z"/></svg> Become a sponsor</a>
|
|
21
|
+
</nav>
|
|
22
|
+
</header>
|
|
23
|
+
|
|
24
|
+
<div class="docs-layout">
|
|
25
|
+
|
|
26
|
+
<aside class="docs-sidebar">
|
|
27
|
+
<div class="sidebar-inner">
|
|
28
|
+
<nav class="docs-nav"><ul class="top-links"><li><a href="/docs/">Home</a></li><li><a href="/docs/whats-new.html">What's new</a></li><li><a href="/docs/reference.html">Command reference</a></li><li><a href="/docs/gallery/">Gallery</a></li></ul><h2>Getting started</h2><ul><li><a href="/docs/essentials/command-line.html">The command-line tool</a></li><li><a href="/docs/essentials/web-app.html">The web app</a></li></ul><h2>Guides</h2><ul><li><a href="/docs/guides/simplification.html">Simplification</a></li><li><a href="/docs/guides/expressions.html">JavaScript expressions</a></li><li><a href="/docs/guides/projections.html">Projections</a></li><li><a href="/docs/guides/topology.html">Topology and cleaning</a></li><li><a href="/docs/guides/combining-layers.html">Combining two layers</a></li><li><a href="/docs/guides/programmatic.html">Using Mapshaper from Node.js</a></li></ul><h2>Formats</h2><ul><li><a href="/docs/formats/overview.html">Overview</a></li><li><a href="/docs/formats/shapefile.html">Shapefile</a></li><li><a href="/docs/formats/geojson.html" class="is-active">GeoJSON</a></li><li><a href="/docs/formats/topojson.html">TopoJSON</a></li><li><a href="/docs/formats/geopackage.html">GeoPackage</a></li><li><a href="/docs/formats/flatgeobuf.html">FlatGeobuf</a></li><li><a href="/docs/formats/kml.html">KML / KMZ</a></li><li><a href="/docs/formats/csv.html">CSV / TSV</a></li><li><a href="/docs/formats/dbf.html">DBF</a></li><li><a href="/docs/formats/json.html">JSON records</a></li><li><a href="/docs/formats/svg.html">SVG</a></li><li><a href="/docs/formats/snapshot.html">Mapshaper snapshot</a></li></ul><h2>Examples</h2><ul><li><a href="/docs/examples/basics.html">Basics</a></li><li><a href="/docs/examples/globe.html">Globe</a></li><li><a href="/docs/examples/us-states.html">U.S. state map</a></li></ul></nav>
|
|
29
|
+
</div>
|
|
30
|
+
</aside>
|
|
31
|
+
|
|
32
|
+
<main class="docs-main">
|
|
33
|
+
<article class="docs-article">
|
|
34
|
+
<div class="docs-breadcrumbs"><a href="/docs/">Docs</a> › Formats › GeoJSON</div>
|
|
35
|
+
<h1 id="geojson">GeoJSON</h1>
|
|
36
|
+
<p>GeoJSON is a simple, human-readable format for geospatial vector data. It is used by many web mapping APIs, although formats like TopoJSON, FlatGeobuf, GeoParquet, and vector tiles have replaced it for specific use cases such as large-file efficiency, cloud-optimized access, and tiled rendering.</p>
|
|
37
|
+
<p><strong>File extensions:</strong> <code>.json</code>, <code>.geojson</code> · <strong>Read:</strong> ✓ · <strong>Write:</strong> ✓ · <strong>Multi-layer:</strong> one layer per file (combinable)</p>
|
|
38
|
+
<h3 id="cli-examples">CLI examples</h3>
|
|
39
|
+
<pre><code class="hljs language-bash">mapshaper input.shp -o provinces.geojson
|
|
40
|
+
mapshaper input.shp -o precision=0.001 prettify provinces.geojson
|
|
41
|
+
</code></pre>
|
|
42
|
+
<h3 id="format-specific-input-options">Format-specific input options</h3>
|
|
43
|
+
<ul>
|
|
44
|
+
<li><code>id-field=</code> — import the value of each Feature's top-level <code>id</code> property into a data field of the given name.</li>
|
|
45
|
+
<li><code>json-path=</code> — for files where the GeoJSON object is nested inside a larger JSON document, e.g. <code>json-path=data/regions</code>.</li>
|
|
46
|
+
</ul>
|
|
47
|
+
<h3 id="format-specific-output-options">Format-specific output options</h3>
|
|
48
|
+
<ul>
|
|
49
|
+
<li><code>precision=</code> — round coordinates to a fixed precision. This is a simple way to reduce file size.</li>
|
|
50
|
+
<li><code>prettify</code> — pretty-print the JSON with line breaks and indentation.</li>
|
|
51
|
+
<li><code>id-field=</code> — promote one or more attribute fields to the GeoJSON <code>id</code> property (comma-separated; first matching field per layer is used).</li>
|
|
52
|
+
<li><code>bbox</code> — add a <code>bbox</code> array to the top-level FeatureCollection.</li>
|
|
53
|
+
<li><code>extension=</code> — override the default <code>.json</code> extension (e.g. <code>extension=geojson</code>).</li>
|
|
54
|
+
<li><code>combine-layers</code> — merge multiple layers into a single GeoJSON output file (geometries are kept separate as Features, attribute schemas are unioned).</li>
|
|
55
|
+
<li><code>geojson-type=</code> — output a <code>Feature</code>, <code>FeatureCollection</code> or bare <code>GeometryCollection</code> instead of the default FeatureCollection.</li>
|
|
56
|
+
<li><code>no-null-props</code> — emit <code>"properties": {}</code> instead of <code>"properties": null</code> for Features without attributes.</li>
|
|
57
|
+
<li><code>hoist=</code> — promote one or more properties out of the <code>properties</code> object onto the Feature itself. Useful for non-standard consumers like <a href="https://github.com/felt/tippecanoe">tippecanoe</a>.</li>
|
|
58
|
+
<li><code>gj2008</code> — emit pre-RFC-7946 GeoJSON (clockwise outer rings). This option produces files that can be rendered with <code>d3</code>.</li>
|
|
59
|
+
<li><code>ndjson</code> — write one Feature per line as newline-delimited JSON (works with the <a href="/docs/formats/json.html"><code>json</code> records</a> family of options as well).</li>
|
|
60
|
+
<li><code>id-prefix=</code> — prefix layer/feature ids when exporting multiple layers.</li>
|
|
61
|
+
</ul>
|
|
62
|
+
<h3 id="practical-notes">Practical notes</h3>
|
|
63
|
+
<ul>
|
|
64
|
+
<li>The GeoJSON spec states that GeoJSON uses WGS-84 coordinates (the lat-long coordinate system used by GPS), but Mapshaper will also export GeoJSON files with projected coordinates.</li>
|
|
65
|
+
<li>Coordinates are emitted at full precision — consider <code>precision=</code> to reduce file size. <code>precision=0.0001</code> equates to ~11 m at the equator, ~8 m in New York City, and ~6 m in Reykjavík, Iceland.</li>
|
|
66
|
+
<li>Polygon ring winding follows RFC 7946 (CCW outer, CW holes); the <code>gj2008</code> option outputs the CW outer rings expected by <code>d3</code>.</li>
|
|
67
|
+
<li>Output is minified by default; pass <code>prettify</code> for human-readable JSON.</li>
|
|
68
|
+
<li>If you are loading the data into a web map and you want the smallest possible file size, consider <a href="/docs/formats/topojson.html">TopoJSON</a> as an alternative to GeoJSON. For datasets with shared boundaries, file sizes are often a fraction of the equivalent GeoJSON size.</li>
|
|
69
|
+
<li><code>precision=</code> rounding can introduce sliver overlaps at boundaries. Pair it with <code>fix-geometry</code> if downstream tools are strict.</li>
|
|
70
|
+
</ul>
|
|
71
|
+
<h3 id="reading-very-large-geojson-files">Reading very large GeoJSON files</h3>
|
|
72
|
+
<p>Mapshaper's custom GeoJSON parser is not limited by the ~500 MB ceiling affecting tools that use <code>JSON.parse()</code>.</p>
|
|
73
|
+
<p>In the <a href="/docs/essentials/web-app.html">web app</a>, the theoretical upper bound is around 2 GB per file in most browsers, though in practice the browser may run out of memory and crash well before that. If a GeoJSON is too big to open in the browser, use the CLI instead.</p>
|
|
74
|
+
<p><code>mapshaper-xl</code> can handle multi-gigabyte files. It allocates 8 GB of memory by default, but you can assign more.</p>
|
|
75
|
+
<pre><code class="hljs language-bash">mapshaper-xl huge.geojson -info
|
|
76
|
+
mapshaper-xl 32gb huge.geojson -simplify 5% -o huge.topojson
|
|
77
|
+
</code></pre>
|
|
78
|
+
<h2 id="external-resources">External resources</h2>
|
|
79
|
+
<ul>
|
|
80
|
+
<li><a href="https://datatracker.ietf.org/doc/html/rfc7946">RFC 7946: The GeoJSON Format</a> — the IETF specification Mapshaper writes by default.</li>
|
|
81
|
+
<li><a href="https://macwright.com/2015/03/23/geojson-second-bite.html">More than you ever wanted to know about GeoJSON</a> — Tom MacWright's detailed practical introduction.</li>
|
|
82
|
+
<li><a href="https://geojson.org/">geojson.org</a> — spec home with links to tooling and validators.</li>
|
|
83
|
+
</ul>
|
|
84
|
+
|
|
85
|
+
<div class="edit-link">
|
|
86
|
+
<a href="https://github.com/mbloch/mapshaper/edit/master/docs/formats/geojson.md">Edit this page on GitHub</a>
|
|
87
|
+
</div>
|
|
88
|
+
</article>
|
|
89
|
+
</main>
|
|
90
|
+
|
|
91
|
+
<aside class="docs-toc">
|
|
92
|
+
<div class="docs-toc-title">On this page</div><ul><li class="lvl-3"><a href="#cli-examples">CLI examples</a></li><li class="lvl-3"><a href="#format-specific-input-options">Format-specific input options</a></li><li class="lvl-3"><a href="#format-specific-output-options">Format-specific output options</a></li><li class="lvl-3"><a href="#practical-notes">Practical notes</a></li><li class="lvl-3"><a href="#reading-very-large-geojson-files">Reading very large GeoJSON files</a></li><li class="lvl-2"><a href="#external-resources">External resources</a></li></ul>
|
|
93
|
+
</aside>
|
|
94
|
+
|
|
95
|
+
</div>
|
|
96
|
+
|
|
97
|
+
<script src="/docs/_assets/docs.js" defer></script>
|
|
98
|
+
|
|
99
|
+
<footer class="docs-footer">
|
|
100
|
+
<div class="docs-footer-inner">
|
|
101
|
+
<span>mapshaper is free software, licensed under <a href="https://www.mozilla.org/MPL/2.0/">MPL 2.0</a>.</span>
|
|
102
|
+
<span><a href="/privacy.html">Privacy</a> · <a href="/terms.html">Terms</a> · <a href="/sponsor.html">Support mapshaper</a></span>
|
|
103
|
+
</div>
|
|
104
|
+
</footer>
|
|
105
|
+
|
|
106
|
+
</body>
|
|
107
|
+
</html>
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: GeoJSON
|
|
3
|
+
description: How Mapshaper reads and writes GeoJSON, including precision, ndjson and RFC 7946 options.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# GeoJSON
|
|
7
|
+
|
|
8
|
+
GeoJSON is a simple, human-readable format for geospatial vector data. It is used by many web mapping APIs, although formats like TopoJSON, FlatGeobuf, GeoParquet, and vector tiles have replaced it for specific use cases such as large-file efficiency, cloud-optimized access, and tiled rendering.
|
|
9
|
+
|
|
10
|
+
**File extensions:** `.json`, `.geojson` · **Read:** ✓ · **Write:** ✓ · **Multi-layer:** one layer per file (combinable)
|
|
11
|
+
|
|
12
|
+
### CLI examples
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
mapshaper input.shp -o provinces.geojson
|
|
16
|
+
mapshaper input.shp -o precision=0.001 prettify provinces.geojson
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
### Format-specific input options
|
|
20
|
+
|
|
21
|
+
- `id-field=` — import the value of each Feature's top-level `id` property into a data field of the given name.
|
|
22
|
+
- `json-path=` — for files where the GeoJSON object is nested inside a larger JSON document, e.g. `json-path=data/regions`.
|
|
23
|
+
|
|
24
|
+
### Format-specific output options
|
|
25
|
+
|
|
26
|
+
- `precision=` — round coordinates to a fixed precision. This is a simple way to reduce file size.
|
|
27
|
+
- `prettify` — pretty-print the JSON with line breaks and indentation.
|
|
28
|
+
- `id-field=` — promote one or more attribute fields to the GeoJSON `id` property (comma-separated; first matching field per layer is used).
|
|
29
|
+
- `bbox` — add a `bbox` array to the top-level FeatureCollection.
|
|
30
|
+
- `extension=` — override the default `.json` extension (e.g. `extension=geojson`).
|
|
31
|
+
- `combine-layers` — merge multiple layers into a single GeoJSON output file (geometries are kept separate as Features, attribute schemas are unioned).
|
|
32
|
+
- `geojson-type=` — output a `Feature`, `FeatureCollection` or bare `GeometryCollection` instead of the default FeatureCollection.
|
|
33
|
+
- `no-null-props` — emit `"properties": {}` instead of `"properties": null` for Features without attributes.
|
|
34
|
+
- `hoist=` — promote one or more properties out of the `properties` object onto the Feature itself. Useful for non-standard consumers like [tippecanoe](https://github.com/felt/tippecanoe).
|
|
35
|
+
- `gj2008` — emit pre-RFC-7946 GeoJSON (clockwise outer rings). This option produces files that can be rendered with `d3`.
|
|
36
|
+
- `ndjson` — write one Feature per line as newline-delimited JSON (works with the [`json` records](/docs/formats/json.html.md) family of options as well).
|
|
37
|
+
- `id-prefix=` — prefix layer/feature ids when exporting multiple layers.
|
|
38
|
+
|
|
39
|
+
### Practical notes
|
|
40
|
+
|
|
41
|
+
- The GeoJSON spec states that GeoJSON uses WGS-84 coordinates (the lat-long coordinate system used by GPS), but Mapshaper will also export GeoJSON files with projected coordinates.
|
|
42
|
+
- Coordinates are emitted at full precision — consider `precision=` to reduce file size. `precision=0.0001` equates to ~11 m at the equator, ~8 m in New York City, and ~6 m in Reykjavík, Iceland.
|
|
43
|
+
- Polygon ring winding follows RFC 7946 (CCW outer, CW holes); the `gj2008` option outputs the CW outer rings expected by `d3`.
|
|
44
|
+
- Output is minified by default; pass `prettify` for human-readable JSON.
|
|
45
|
+
- If you are loading the data into a web map and you want the smallest possible file size, consider [TopoJSON](/docs/formats/topojson.html.md) as an alternative to GeoJSON. For datasets with shared boundaries, file sizes are often a fraction of the equivalent GeoJSON size.
|
|
46
|
+
- `precision=` rounding can introduce sliver overlaps at boundaries. Pair it with `fix-geometry` if downstream tools are strict.
|
|
47
|
+
|
|
48
|
+
### Reading very large GeoJSON files
|
|
49
|
+
|
|
50
|
+
Mapshaper's custom GeoJSON parser is not limited by the ~500 MB ceiling affecting tools that use `JSON.parse()`.
|
|
51
|
+
|
|
52
|
+
In the [web app](/docs/essentials/web-app.html.md), the theoretical upper bound is around 2 GB per file in most browsers, though in practice the browser may run out of memory and crash well before that. If a GeoJSON is too big to open in the browser, use the CLI instead.
|
|
53
|
+
|
|
54
|
+
`mapshaper-xl` can handle multi-gigabyte files. It allocates 8 GB of memory by default, but you can assign more.
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
mapshaper-xl huge.geojson -info
|
|
58
|
+
mapshaper-xl 32gb huge.geojson -simplify 5% -o huge.topojson
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## External resources
|
|
62
|
+
|
|
63
|
+
- [RFC 7946: The GeoJSON Format](https://datatracker.ietf.org/doc/html/rfc7946) — the IETF specification Mapshaper writes by default.
|
|
64
|
+
- [More than you ever wanted to know about GeoJSON](https://macwright.com/2015/03/23/geojson-second-bite.html) — Tom MacWright's detailed practical introduction.
|
|
65
|
+
- [geojson.org](https://geojson.org/) — spec home with links to tooling and validators.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
<!DOCTYPE html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="UTF-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
+
<title>GeoPackage · mapshaper docs</title>
|
|
7
|
+
<meta name="description" content="How Mapshaper reads and writes GeoPackage (.gpkg), the OGC's SQLite-based GIS container.">
|
|
8
|
+
<link rel="icon" type="image/png" href="/images/icon.png">
|
|
9
|
+
<link rel="stylesheet" href="/docs/_assets/highlight.css">
|
|
10
|
+
<link rel="stylesheet" href="/docs/_assets/docs.css">
|
|
11
|
+
</head>
|
|
12
|
+
<body class="">
|
|
13
|
+
|
|
14
|
+
<header class="page-header">
|
|
15
|
+
<a href="/" class="mapshaper-logo">map<span class="logo-highlight">shaper</span></a>
|
|
16
|
+
<span class="header-section-label">Docs</span>
|
|
17
|
+
<nav class="header-nav">
|
|
18
|
+
<a href="/">Web app</a>
|
|
19
|
+
<a href="https://github.com/mbloch/mapshaper">GitHub</a>
|
|
20
|
+
<a href="/sponsor.html" class="sponsor-link"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z"/></svg> Become a sponsor</a>
|
|
21
|
+
</nav>
|
|
22
|
+
</header>
|
|
23
|
+
|
|
24
|
+
<div class="docs-layout">
|
|
25
|
+
|
|
26
|
+
<aside class="docs-sidebar">
|
|
27
|
+
<div class="sidebar-inner">
|
|
28
|
+
<nav class="docs-nav"><ul class="top-links"><li><a href="/docs/">Home</a></li><li><a href="/docs/whats-new.html">What's new</a></li><li><a href="/docs/reference.html">Command reference</a></li><li><a href="/docs/gallery/">Gallery</a></li></ul><h2>Getting started</h2><ul><li><a href="/docs/essentials/command-line.html">The command-line tool</a></li><li><a href="/docs/essentials/web-app.html">The web app</a></li></ul><h2>Guides</h2><ul><li><a href="/docs/guides/simplification.html">Simplification</a></li><li><a href="/docs/guides/expressions.html">JavaScript expressions</a></li><li><a href="/docs/guides/projections.html">Projections</a></li><li><a href="/docs/guides/topology.html">Topology and cleaning</a></li><li><a href="/docs/guides/combining-layers.html">Combining two layers</a></li><li><a href="/docs/guides/programmatic.html">Using Mapshaper from Node.js</a></li></ul><h2>Formats</h2><ul><li><a href="/docs/formats/overview.html">Overview</a></li><li><a href="/docs/formats/shapefile.html">Shapefile</a></li><li><a href="/docs/formats/geojson.html">GeoJSON</a></li><li><a href="/docs/formats/topojson.html">TopoJSON</a></li><li><a href="/docs/formats/geopackage.html" class="is-active">GeoPackage</a></li><li><a href="/docs/formats/flatgeobuf.html">FlatGeobuf</a></li><li><a href="/docs/formats/kml.html">KML / KMZ</a></li><li><a href="/docs/formats/csv.html">CSV / TSV</a></li><li><a href="/docs/formats/dbf.html">DBF</a></li><li><a href="/docs/formats/json.html">JSON records</a></li><li><a href="/docs/formats/svg.html">SVG</a></li><li><a href="/docs/formats/snapshot.html">Mapshaper snapshot</a></li></ul><h2>Examples</h2><ul><li><a href="/docs/examples/basics.html">Basics</a></li><li><a href="/docs/examples/globe.html">Globe</a></li><li><a href="/docs/examples/us-states.html">U.S. state map</a></li></ul></nav>
|
|
29
|
+
</div>
|
|
30
|
+
</aside>
|
|
31
|
+
|
|
32
|
+
<main class="docs-main">
|
|
33
|
+
<article class="docs-article">
|
|
34
|
+
<div class="docs-breadcrumbs"><a href="/docs/">Docs</a> › Formats › GeoPackage</div>
|
|
35
|
+
<h1 id="geopackage">GeoPackage</h1>
|
|
36
|
+
<p>GeoPackage is the OGC's modern, open replacement for Shapefile — a single SQLite database file that holds one or many vector layers along with their CRS metadata. It solves most of Shapefile's problems (long field names, UTF-8 encoding, no companion files, multiple layers per file, no 2 GB cap) and is well-supported across QGIS, ArcGIS and <code>ogr2ogr</code>.</p>
|
|
37
|
+
<p><strong>File extension:</strong> <code>.gpkg</code> · <strong>Read:</strong> ✓ · <strong>Write:</strong> ✓ · <strong>Multi-layer:</strong> ✓</p>
|
|
38
|
+
<h3 id="cli-examples">CLI examples</h3>
|
|
39
|
+
<pre><code class="hljs language-bash">mapshaper basemap.gpkg -info
|
|
40
|
+
mapshaper basemap.gpkg -o format=geojson regions.geojson
|
|
41
|
+
mapshaper -i basemap.gpkg layers=provinces,cities -info
|
|
42
|
+
mapshaper provinces.shp -o provinces.gpkg
|
|
43
|
+
mapshaper a.shp b.shp -o combined.gpkg
|
|
44
|
+
</code></pre>
|
|
45
|
+
<h3 id="format-specific-input-options">Format-specific input options</h3>
|
|
46
|
+
<ul>
|
|
47
|
+
<li><code>layers=</code> — comma-separated list of layer names to import. Useful for picking a subset out of a large multi-layer GeoPackage. Omit to import everything.</li>
|
|
48
|
+
</ul>
|
|
49
|
+
<h3 id="format-specific-output-options">Format-specific output options</h3>
|
|
50
|
+
<p>There are no GeoPackage-specific <code>-o</code> options. The format honors the general flags (<code>precision=</code>, <code>gzip</code>, <code>zip</code>, etc.) where they apply.</p>
|
|
51
|
+
<h3 id="practical-notes">Practical notes</h3>
|
|
52
|
+
<ul>
|
|
53
|
+
<li>By default, every vector layer in the file is imported as a separate Mapshaper layer. To pick a subset, use the <code>layers=</code> option on the CLI; in the web app, tick the <strong>with advanced options</strong> checkbox in the import dialog to bring up a per-layer selection list.</li>
|
|
54
|
+
<li>When multiple layers are exported to a single <code>.gpkg</code>, each becomes a separate layer table inside the database, named after the source layer.</li>
|
|
55
|
+
<li>Raster tile layers (the OGC GeoPackage spec also covers tiles) are ignored — Mapshaper is vector-only.</li>
|
|
56
|
+
</ul>
|
|
57
|
+
<h2 id="external-resources">External resources</h2>
|
|
58
|
+
<ul>
|
|
59
|
+
<li><a href="https://www.geopackage.org/">geopackage.org</a> — project home with spec, FAQs and tool support.</li>
|
|
60
|
+
<li><a href="https://docs.qgis.org/latest/en/docs/user_manual/managing_data_source/supported_data.html">QGIS user manual: supported data formats</a> — the practical reference on how QGIS treats GeoPackage, including multi-layer use and project storage.</li>
|
|
61
|
+
<li><a href="https://www.gispo.fi/en/blog/learn-spatial-sql-and-master-geopackage-with-qgis-3/">Learn spatial SQL and master GeoPackage with QGIS</a> — tutorial from Gispo showing how to query GeoPackage layers with SQL directly from QGIS.</li>
|
|
62
|
+
<li>GeoPackage reading and writing in Mapshaper is delegated to NGA's <a href="https://github.com/ngageoint/geopackage-js"><code>@ngageoint/geopackage</code></a> library, which handles the underlying SQLite database, the OGC table schemas and the WKB-to-GeoJSON geometry conversions.</li>
|
|
63
|
+
</ul>
|
|
64
|
+
|
|
65
|
+
<div class="edit-link">
|
|
66
|
+
<a href="https://github.com/mbloch/mapshaper/edit/master/docs/formats/geopackage.md">Edit this page on GitHub</a>
|
|
67
|
+
</div>
|
|
68
|
+
</article>
|
|
69
|
+
</main>
|
|
70
|
+
|
|
71
|
+
<aside class="docs-toc">
|
|
72
|
+
<div class="docs-toc-title">On this page</div><ul><li class="lvl-3"><a href="#cli-examples">CLI examples</a></li><li class="lvl-3"><a href="#format-specific-input-options">Format-specific input options</a></li><li class="lvl-3"><a href="#format-specific-output-options">Format-specific output options</a></li><li class="lvl-3"><a href="#practical-notes">Practical notes</a></li><li class="lvl-2"><a href="#external-resources">External resources</a></li></ul>
|
|
73
|
+
</aside>
|
|
74
|
+
|
|
75
|
+
</div>
|
|
76
|
+
|
|
77
|
+
<script src="/docs/_assets/docs.js" defer></script>
|
|
78
|
+
|
|
79
|
+
<footer class="docs-footer">
|
|
80
|
+
<div class="docs-footer-inner">
|
|
81
|
+
<span>mapshaper is free software, licensed under <a href="https://www.mozilla.org/MPL/2.0/">MPL 2.0</a>.</span>
|
|
82
|
+
<span><a href="/privacy.html">Privacy</a> · <a href="/terms.html">Terms</a> · <a href="/sponsor.html">Support mapshaper</a></span>
|
|
83
|
+
</div>
|
|
84
|
+
</footer>
|
|
85
|
+
|
|
86
|
+
</body>
|
|
87
|
+
</html>
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: GeoPackage
|
|
3
|
+
description: How Mapshaper reads and writes GeoPackage (.gpkg), the OGC's SQLite-based GIS container.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# GeoPackage
|
|
7
|
+
|
|
8
|
+
GeoPackage is the OGC's modern, open replacement for Shapefile — a single SQLite database file that holds one or many vector layers along with their CRS metadata. It solves most of Shapefile's problems (long field names, UTF-8 encoding, no companion files, multiple layers per file, no 2 GB cap) and is well-supported across QGIS, ArcGIS and `ogr2ogr`.
|
|
9
|
+
|
|
10
|
+
**File extension:** `.gpkg` · **Read:** ✓ · **Write:** ✓ · **Multi-layer:** ✓
|
|
11
|
+
|
|
12
|
+
### CLI examples
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
mapshaper basemap.gpkg -info
|
|
16
|
+
mapshaper basemap.gpkg -o format=geojson regions.geojson
|
|
17
|
+
mapshaper -i basemap.gpkg layers=provinces,cities -info
|
|
18
|
+
mapshaper provinces.shp -o provinces.gpkg
|
|
19
|
+
mapshaper a.shp b.shp -o combined.gpkg
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
### Format-specific input options
|
|
23
|
+
|
|
24
|
+
- `layers=` — comma-separated list of layer names to import. Useful for picking a subset out of a large multi-layer GeoPackage. Omit to import everything.
|
|
25
|
+
|
|
26
|
+
### Format-specific output options
|
|
27
|
+
|
|
28
|
+
There are no GeoPackage-specific `-o` options. The format honors the general flags (`precision=`, `gzip`, `zip`, etc.) where they apply.
|
|
29
|
+
|
|
30
|
+
### Practical notes
|
|
31
|
+
|
|
32
|
+
- By default, every vector layer in the file is imported as a separate Mapshaper layer. To pick a subset, use the `layers=` option on the CLI; in the web app, tick the **with advanced options** checkbox in the import dialog to bring up a per-layer selection list.
|
|
33
|
+
- When multiple layers are exported to a single `.gpkg`, each becomes a separate layer table inside the database, named after the source layer.
|
|
34
|
+
- Raster tile layers (the OGC GeoPackage spec also covers tiles) are ignored — Mapshaper is vector-only.
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
## External resources
|
|
38
|
+
|
|
39
|
+
- [geopackage.org](https://www.geopackage.org/) — project home with spec, FAQs and tool support.
|
|
40
|
+
- [QGIS user manual: supported data formats](https://docs.qgis.org/latest/en/docs/user_manual/managing_data_source/supported_data.html) — the practical reference on how QGIS treats GeoPackage, including multi-layer use and project storage.
|
|
41
|
+
- [Learn spatial SQL and master GeoPackage with QGIS](https://www.gispo.fi/en/blog/learn-spatial-sql-and-master-geopackage-with-qgis-3/) — tutorial from Gispo showing how to query GeoPackage layers with SQL directly from QGIS.
|
|
42
|
+
- GeoPackage reading and writing in Mapshaper is delegated to NGA's [`@ngageoint/geopackage`](https://github.com/ngageoint/geopackage-js) library, which handles the underlying SQLite database, the OGC table schemas and the WKB-to-GeoJSON geometry conversions.
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
<!DOCTYPE html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="UTF-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
+
<title>JSON records · mapshaper docs</title>
|
|
7
|
+
<meta name="description" content="How Mapshaper reads and writes plain JSON arrays of objects (no geometry), useful for tabular data exchange.">
|
|
8
|
+
<link rel="icon" type="image/png" href="/images/icon.png">
|
|
9
|
+
<link rel="stylesheet" href="/docs/_assets/highlight.css">
|
|
10
|
+
<link rel="stylesheet" href="/docs/_assets/docs.css">
|
|
11
|
+
</head>
|
|
12
|
+
<body class="">
|
|
13
|
+
|
|
14
|
+
<header class="page-header">
|
|
15
|
+
<a href="/" class="mapshaper-logo">map<span class="logo-highlight">shaper</span></a>
|
|
16
|
+
<span class="header-section-label">Docs</span>
|
|
17
|
+
<nav class="header-nav">
|
|
18
|
+
<a href="/">Web app</a>
|
|
19
|
+
<a href="https://github.com/mbloch/mapshaper">GitHub</a>
|
|
20
|
+
<a href="/sponsor.html" class="sponsor-link"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z"/></svg> Become a sponsor</a>
|
|
21
|
+
</nav>
|
|
22
|
+
</header>
|
|
23
|
+
|
|
24
|
+
<div class="docs-layout">
|
|
25
|
+
|
|
26
|
+
<aside class="docs-sidebar">
|
|
27
|
+
<div class="sidebar-inner">
|
|
28
|
+
<nav class="docs-nav"><ul class="top-links"><li><a href="/docs/">Home</a></li><li><a href="/docs/whats-new.html">What's new</a></li><li><a href="/docs/reference.html">Command reference</a></li><li><a href="/docs/gallery/">Gallery</a></li></ul><h2>Getting started</h2><ul><li><a href="/docs/essentials/command-line.html">The command-line tool</a></li><li><a href="/docs/essentials/web-app.html">The web app</a></li></ul><h2>Guides</h2><ul><li><a href="/docs/guides/simplification.html">Simplification</a></li><li><a href="/docs/guides/expressions.html">JavaScript expressions</a></li><li><a href="/docs/guides/projections.html">Projections</a></li><li><a href="/docs/guides/topology.html">Topology and cleaning</a></li><li><a href="/docs/guides/combining-layers.html">Combining two layers</a></li><li><a href="/docs/guides/programmatic.html">Using Mapshaper from Node.js</a></li></ul><h2>Formats</h2><ul><li><a href="/docs/formats/overview.html">Overview</a></li><li><a href="/docs/formats/shapefile.html">Shapefile</a></li><li><a href="/docs/formats/geojson.html">GeoJSON</a></li><li><a href="/docs/formats/topojson.html">TopoJSON</a></li><li><a href="/docs/formats/geopackage.html">GeoPackage</a></li><li><a href="/docs/formats/flatgeobuf.html">FlatGeobuf</a></li><li><a href="/docs/formats/kml.html">KML / KMZ</a></li><li><a href="/docs/formats/csv.html">CSV / TSV</a></li><li><a href="/docs/formats/dbf.html">DBF</a></li><li><a href="/docs/formats/json.html" class="is-active">JSON records</a></li><li><a href="/docs/formats/svg.html">SVG</a></li><li><a href="/docs/formats/snapshot.html">Mapshaper snapshot</a></li></ul><h2>Examples</h2><ul><li><a href="/docs/examples/basics.html">Basics</a></li><li><a href="/docs/examples/globe.html">Globe</a></li><li><a href="/docs/examples/us-states.html">U.S. state map</a></li></ul></nav>
|
|
29
|
+
</div>
|
|
30
|
+
</aside>
|
|
31
|
+
|
|
32
|
+
<main class="docs-main">
|
|
33
|
+
<article class="docs-article">
|
|
34
|
+
<div class="docs-breadcrumbs"><a href="/docs/">Docs</a> › Formats › JSON records</div>
|
|
35
|
+
<h1 id="json-records">JSON records</h1>
|
|
36
|
+
<p>A JSON-records file is a plain JSON array of objects, one per record, with no geometry.</p>
|
|
37
|
+
<p><strong>File extension:</strong> <code>.json</code> · <strong>Read:</strong> ✓ · <strong>Write:</strong> ✓ · <strong>Geometry:</strong> none</p>
|
|
38
|
+
<p>A JSON-records file looks like this:</p>
|
|
39
|
+
<pre><code class="hljs language-json"><span class="hljs-punctuation">[</span>
|
|
40
|
+
<span class="hljs-punctuation">{</span> <span class="hljs-attr">"id"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"name"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Alice"</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"city"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Toronto"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
|
|
41
|
+
<span class="hljs-punctuation">{</span> <span class="hljs-attr">"id"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">2</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"name"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Bob"</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"city"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Vancouver"</span> <span class="hljs-punctuation">}</span>
|
|
42
|
+
<span class="hljs-punctuation">]</span>
|
|
43
|
+
</code></pre>
|
|
44
|
+
<h3 id="format-specific-input-options">Format-specific input options</h3>
|
|
45
|
+
<ul>
|
|
46
|
+
<li><code>json-path=</code> — for files where the array is nested inside a larger object, e.g. <code>json-path=data/records</code> for <code>{"data": {"records": [...]}}</code>.</li>
|
|
47
|
+
</ul>
|
|
48
|
+
<h3 id="format-specific-output-options">Format-specific output options</h3>
|
|
49
|
+
<ul>
|
|
50
|
+
<li><code>ndjson</code> — emit newline-delimited JSON instead of an array. One record per line. Often easier to process with line-oriented tools.</li>
|
|
51
|
+
</ul>
|
|
52
|
+
<h3 id="practical-notes">Practical notes</h3>
|
|
53
|
+
<ul>
|
|
54
|
+
<li>When exporting non-tabular layers as JSON records, the geometry is dropped — you get just the attribute table as JSON.</li>
|
|
55
|
+
</ul>
|
|
56
|
+
<h2 id="external-resources">External resources</h2>
|
|
57
|
+
<ul>
|
|
58
|
+
<li><a href="https://jsonlines.org/">JSON Lines (jsonlines.org)</a> — the spec for the newline-delimited JSON variant emitted by Mapshaper's <code>ndjson</code> option.</li>
|
|
59
|
+
</ul>
|
|
60
|
+
|
|
61
|
+
<div class="edit-link">
|
|
62
|
+
<a href="https://github.com/mbloch/mapshaper/edit/master/docs/formats/json.md">Edit this page on GitHub</a>
|
|
63
|
+
</div>
|
|
64
|
+
</article>
|
|
65
|
+
</main>
|
|
66
|
+
|
|
67
|
+
<aside class="docs-toc">
|
|
68
|
+
<div class="docs-toc-title">On this page</div><ul><li class="lvl-3"><a href="#format-specific-input-options">Format-specific input options</a></li><li class="lvl-3"><a href="#format-specific-output-options">Format-specific output options</a></li><li class="lvl-3"><a href="#practical-notes">Practical notes</a></li><li class="lvl-2"><a href="#external-resources">External resources</a></li></ul>
|
|
69
|
+
</aside>
|
|
70
|
+
|
|
71
|
+
</div>
|
|
72
|
+
|
|
73
|
+
<script src="/docs/_assets/docs.js" defer></script>
|
|
74
|
+
|
|
75
|
+
<footer class="docs-footer">
|
|
76
|
+
<div class="docs-footer-inner">
|
|
77
|
+
<span>mapshaper is free software, licensed under <a href="https://www.mozilla.org/MPL/2.0/">MPL 2.0</a>.</span>
|
|
78
|
+
<span><a href="/privacy.html">Privacy</a> · <a href="/terms.html">Terms</a> · <a href="/sponsor.html">Support mapshaper</a></span>
|
|
79
|
+
</div>
|
|
80
|
+
</footer>
|
|
81
|
+
|
|
82
|
+
</body>
|
|
83
|
+
</html>
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: JSON records
|
|
3
|
+
description: How Mapshaper reads and writes plain JSON arrays of objects (no geometry), useful for tabular data exchange.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# JSON records
|
|
7
|
+
|
|
8
|
+
A JSON-records file is a plain JSON array of objects, one per record, with no geometry.
|
|
9
|
+
|
|
10
|
+
**File extension:** `.json` · **Read:** ✓ · **Write:** ✓ · **Geometry:** none
|
|
11
|
+
|
|
12
|
+
A JSON-records file looks like this:
|
|
13
|
+
|
|
14
|
+
```json
|
|
15
|
+
[
|
|
16
|
+
{ "id": 1, "name": "Alice", "city": "Toronto" },
|
|
17
|
+
{ "id": 2, "name": "Bob", "city": "Vancouver" }
|
|
18
|
+
]
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
### Format-specific input options
|
|
22
|
+
|
|
23
|
+
- `json-path=` — for files where the array is nested inside a larger object, e.g. `json-path=data/records` for `{"data": {"records": [...]}}`.
|
|
24
|
+
|
|
25
|
+
### Format-specific output options
|
|
26
|
+
|
|
27
|
+
- `ndjson` — emit newline-delimited JSON instead of an array. One record per line. Often easier to process with line-oriented tools.
|
|
28
|
+
|
|
29
|
+
### Practical notes
|
|
30
|
+
|
|
31
|
+
- When exporting non-tabular layers as JSON records, the geometry is dropped — you get just the attribute table as JSON.
|
|
32
|
+
|
|
33
|
+
## External resources
|
|
34
|
+
|
|
35
|
+
- [JSON Lines (jsonlines.org)](https://jsonlines.org/) — the spec for the newline-delimited JSON variant emitted by Mapshaper's `ndjson` option.
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
<!DOCTYPE html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="UTF-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
+
<title>KML and KMZ · mapshaper docs</title>
|
|
7
|
+
<meta name="description" content="How Mapshaper reads and writes KML and KMZ files for use with Google Earth and similar tools.">
|
|
8
|
+
<link rel="icon" type="image/png" href="/images/icon.png">
|
|
9
|
+
<link rel="stylesheet" href="/docs/_assets/highlight.css">
|
|
10
|
+
<link rel="stylesheet" href="/docs/_assets/docs.css">
|
|
11
|
+
</head>
|
|
12
|
+
<body class="">
|
|
13
|
+
|
|
14
|
+
<header class="page-header">
|
|
15
|
+
<a href="/" class="mapshaper-logo">map<span class="logo-highlight">shaper</span></a>
|
|
16
|
+
<span class="header-section-label">Docs</span>
|
|
17
|
+
<nav class="header-nav">
|
|
18
|
+
<a href="/">Web app</a>
|
|
19
|
+
<a href="https://github.com/mbloch/mapshaper">GitHub</a>
|
|
20
|
+
<a href="/sponsor.html" class="sponsor-link"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z"/></svg> Become a sponsor</a>
|
|
21
|
+
</nav>
|
|
22
|
+
</header>
|
|
23
|
+
|
|
24
|
+
<div class="docs-layout">
|
|
25
|
+
|
|
26
|
+
<aside class="docs-sidebar">
|
|
27
|
+
<div class="sidebar-inner">
|
|
28
|
+
<nav class="docs-nav"><ul class="top-links"><li><a href="/docs/">Home</a></li><li><a href="/docs/whats-new.html">What's new</a></li><li><a href="/docs/reference.html">Command reference</a></li><li><a href="/docs/gallery/">Gallery</a></li></ul><h2>Getting started</h2><ul><li><a href="/docs/essentials/command-line.html">The command-line tool</a></li><li><a href="/docs/essentials/web-app.html">The web app</a></li></ul><h2>Guides</h2><ul><li><a href="/docs/guides/simplification.html">Simplification</a></li><li><a href="/docs/guides/expressions.html">JavaScript expressions</a></li><li><a href="/docs/guides/projections.html">Projections</a></li><li><a href="/docs/guides/topology.html">Topology and cleaning</a></li><li><a href="/docs/guides/combining-layers.html">Combining two layers</a></li><li><a href="/docs/guides/programmatic.html">Using Mapshaper from Node.js</a></li></ul><h2>Formats</h2><ul><li><a href="/docs/formats/overview.html">Overview</a></li><li><a href="/docs/formats/shapefile.html">Shapefile</a></li><li><a href="/docs/formats/geojson.html">GeoJSON</a></li><li><a href="/docs/formats/topojson.html">TopoJSON</a></li><li><a href="/docs/formats/geopackage.html">GeoPackage</a></li><li><a href="/docs/formats/flatgeobuf.html">FlatGeobuf</a></li><li><a href="/docs/formats/kml.html" class="is-active">KML / KMZ</a></li><li><a href="/docs/formats/csv.html">CSV / TSV</a></li><li><a href="/docs/formats/dbf.html">DBF</a></li><li><a href="/docs/formats/json.html">JSON records</a></li><li><a href="/docs/formats/svg.html">SVG</a></li><li><a href="/docs/formats/snapshot.html">Mapshaper snapshot</a></li></ul><h2>Examples</h2><ul><li><a href="/docs/examples/basics.html">Basics</a></li><li><a href="/docs/examples/globe.html">Globe</a></li><li><a href="/docs/examples/us-states.html">U.S. state map</a></li></ul></nav>
|
|
29
|
+
</div>
|
|
30
|
+
</aside>
|
|
31
|
+
|
|
32
|
+
<main class="docs-main">
|
|
33
|
+
<article class="docs-article">
|
|
34
|
+
<div class="docs-breadcrumbs"><a href="/docs/">Docs</a> › Formats › KML / KMZ</div>
|
|
35
|
+
<h1 id="kml-and-kmz">KML and KMZ</h1>
|
|
36
|
+
<p>KML is Google's XML-based format for geographic data, originally created for Google Earth and now an OGC standard. KMZ is a zipped KML. KML emphasises display (icons, styles, balloons) over attributes, so it's most useful for handing files to viewers like Google Earth, mobile mapping apps and Google My Maps — as a data interchange format it has weaker attribute typing and schema support than <a href="/docs/formats/geojson.html">GeoJSON</a> or <a href="/docs/formats/shapefile.html">Shapefile</a>.</p>
|
|
37
|
+
<p><strong>File extensions:</strong> <code>.kml</code>, <code>.kmz</code> · <strong>Read:</strong> ✓ · <strong>Write:</strong> ✓ · <strong>Multi-layer:</strong> ✓</p>
|
|
38
|
+
<h3 id="cli-examples">CLI examples</h3>
|
|
39
|
+
<pre><code class="hljs language-bash">mapshaper places.kml -info
|
|
40
|
+
mapshaper places.kmz -o format=geojson places.geojson
|
|
41
|
+
mapshaper provinces.shp -proj wgs84 -o provinces.kml
|
|
42
|
+
</code></pre>
|
|
43
|
+
<h3 id="format-specific-input-options">Format-specific input options</h3>
|
|
44
|
+
<p>There are no KML-specific <code>-i</code> options. Encoding is always UTF-8 per the KML spec.</p>
|
|
45
|
+
<h3 id="format-specific-output-options">Format-specific output options</h3>
|
|
46
|
+
<p>There are no KML-specific <code>-o</code> options.</p>
|
|
47
|
+
<h3 id="practical-notes">Practical notes</h3>
|
|
48
|
+
<ul>
|
|
49
|
+
<li>KML stores all attribute values as strings, so numeric attributes are imported as strings.</li>
|
|
50
|
+
<li>KML requires WGS84 coordinates, but Mapshaper does <strong>not</strong> reproject on export — coordinates are written through as-is. If your dataset is in any other CRS, run <code>-proj wgs84</code> first, otherwise the output will not be conformant KML and viewers will misplace the geometry.</li>
|
|
51
|
+
</ul>
|
|
52
|
+
<h2 id="external-resources">External resources</h2>
|
|
53
|
+
<ul>
|
|
54
|
+
<li><a href="https://www.ogc.org/standards/kml/">OGC KML standard</a> — the formal OGC specification.</li>
|
|
55
|
+
<li><a href="https://developers.google.com/kml/documentation/kmlreference">Google KML Reference</a> — the practical element-by-element reference; more readable than the OGC spec.</li>
|
|
56
|
+
<li><a href="https://developers.google.com/kml/documentation/kml_tut">Google KML Tutorial</a> — covers how Google Earth interprets the format.</li>
|
|
57
|
+
<li>KML reading and writing in Mapshaper is delegated to two third-party libraries: <a href="https://github.com/placemark/togeojson"><code>@tmcw/togeojson</code></a> for parsing KML into GeoJSON on import, and <a href="https://github.com/placemark/tokml"><code>@placemarkio/tokml</code></a> for serialising GeoJSON back to KML on export.</li>
|
|
58
|
+
</ul>
|
|
59
|
+
|
|
60
|
+
<div class="edit-link">
|
|
61
|
+
<a href="https://github.com/mbloch/mapshaper/edit/master/docs/formats/kml.md">Edit this page on GitHub</a>
|
|
62
|
+
</div>
|
|
63
|
+
</article>
|
|
64
|
+
</main>
|
|
65
|
+
|
|
66
|
+
<aside class="docs-toc">
|
|
67
|
+
<div class="docs-toc-title">On this page</div><ul><li class="lvl-3"><a href="#cli-examples">CLI examples</a></li><li class="lvl-3"><a href="#format-specific-input-options">Format-specific input options</a></li><li class="lvl-3"><a href="#format-specific-output-options">Format-specific output options</a></li><li class="lvl-3"><a href="#practical-notes">Practical notes</a></li><li class="lvl-2"><a href="#external-resources">External resources</a></li></ul>
|
|
68
|
+
</aside>
|
|
69
|
+
|
|
70
|
+
</div>
|
|
71
|
+
|
|
72
|
+
<script src="/docs/_assets/docs.js" defer></script>
|
|
73
|
+
|
|
74
|
+
<footer class="docs-footer">
|
|
75
|
+
<div class="docs-footer-inner">
|
|
76
|
+
<span>mapshaper is free software, licensed under <a href="https://www.mozilla.org/MPL/2.0/">MPL 2.0</a>.</span>
|
|
77
|
+
<span><a href="/privacy.html">Privacy</a> · <a href="/terms.html">Terms</a> · <a href="/sponsor.html">Support mapshaper</a></span>
|
|
78
|
+
</div>
|
|
79
|
+
</footer>
|
|
80
|
+
|
|
81
|
+
</body>
|
|
82
|
+
</html>
|