# TopoJSON Client The **topojson-client** module provides tools for manipulating [TopoJSON](https://github.com/topojson/topojson), such as to [merge shapes](#merge) or [quantize coordinates](#quantize), and for converting back to [GeoJSON](#feature) for rendering with standard tools such as [d3.geoPath](https://github.com/d3/d3-geo/blob/master/README.md#geoPath). For example, [bl.ocks.org/3783604](https://bl.ocks.org/mbostock/3783604): ```html

``` ## Installing If you use NPM, `npm install topojson-client`. Otherwise, download the [latest release](https://github.com/topojson/topojson-client/releases/latest). You can also load directly from [UNPKG](https://unpkg.com) as a [standalone library](https://unpkg.com/topojson-client@3). AMD, CommonJS, and vanilla environments are supported. In vanilla, a `topojson` global is exported: ```html ``` The TopoJSON client API is implemented using ES2015 modules. In compatible environments, you can import the library as a namespace, like so: ```js import * as topojson from "topojson-client"; ``` [Try topojson-client in your browser.](https://runkit.com/npm/topojson-client) # API Reference # topojson.feature(topology, object) [<>](https://github.com/topojson/topojson-client/blob/master/src/feature.js "Source") Returns the GeoJSON Feature or FeatureCollection for the specified *object* in the given *topology*. If the specified object is a string, it is treated as *topology*.objects[*object*]. Then, if the object is a GeometryCollection, a FeatureCollection is returned, and each geometry in the collection is mapped to a Feature. Otherwise, a Feature is returned. The returned feature is a shallow copy of the source *object*: they may share identifiers, bounding boxes, properties and coordinates. Some examples: * A point is mapped to a feature with a geometry object of type “Point”. * Likewise for line strings, polygons, and other simple geometries. * A null geometry object (of type null in TopoJSON) is mapped to a feature with a null geometry object. * A geometry collection of points is mapped to a feature collection of features, each with a point geometry. * A geometry collection of geometry collections is mapped to a feature collection of features, each with a geometry collection. See [feature-test.js](https://github.com/topojson/topojson-client/blob/master/test/feature-test.js) for more examples. # topojson.merge(topology, objects) [<>](https://github.com/topojson/topojson-client/blob/master/src/merge.js#L5 "Source") Returns the GeoJSON MultiPolygon geometry object representing the union for the specified array of Polygon and MultiPolygon *objects* in the given *topology*. Interior borders shared by adjacent polygons are removed. See [Merging States](https://bl.ocks.org/mbostock/5416405) for an example. The returned geometry is a shallow copy of the source *object*: they may share coordinates. # topojson.mergeArcs(topology, objects) [<>](https://github.com/topojson/topojson-client/blob/master/src/merge.js#L9 "Source") Equivalent to [topojson.merge](#merge), but returns TopoJSON rather than GeoJSON. The returned geometry is a shallow copy of the source *object*: they may share coordinates. # topojson.mesh(topology[, object[, filter]]) [<>](https://github.com/topojson/topojson-client/blob/master/src/mesh.js#L4 "Source") Returns the GeoJSON MultiLineString geometry object representing the mesh for the specified *object* in the given *topology*. This is useful for rendering strokes in complicated objects efficiently, as edges that are shared by multiple features are only stroked once. If *object* is not specified, a mesh of the entire topology is returned. The returned geometry is a shallow copy of the source *object*: they may share coordinates. An optional *filter* function may be specified to prune arcs from the returned mesh using the topology. The filter function is called once for each candidate arc and takes two arguments, *a* and *b*, two geometry objects that share that arc. Each arc is only included in the resulting mesh if the filter function returns true. For typical map topologies the geometries *a* and *b* are adjacent polygons and the candidate arc is their boundary. If an arc is only used by a single geometry then *a* and *b* are identical. This property is useful for separating interior and exterior boundaries; an easy way to produce a mesh of interior boundaries is: ```js var interiors = topojson.mesh(topology, object, function(a, b) { return a !== b; }); ``` See this [county choropleth](https://bl.ocks.org/mbostock/4060606) for example. Note: the *a* and *b* objects are TopoJSON objects (pulled directly from the topology), and not automatically converted to GeoJSON features as by [topojson.feature](#feature). # topojson.meshArcs(topology[, object[, filter]]) [<>](https://github.com/topojson/topojson-client/blob/master/src/mesh.js#L8 "Source") Equivalent to [topojson.mesh](#mesh), but returns TopoJSON rather than GeoJSON. The returned geometry is a shallow copy of the source *object*: they may share coordinates. # topojson.neighbors(objects) [<>](https://github.com/topojson/topojson-client/blob/master/src/neighbors.js "Source") Returns an array representing the set of neighboring objects for each object in the specified *objects* array. The returned array has the same number of elements as the input array; each element *i* in the returned array is the array of indexes for neighbors of object *i* in the input array. For example, if the specified objects array contains the features *foo* and *bar*, and these features are neighbors, the returned array will be \[\[1\], \[0\]\], indicating that *foo* is a neighbor of *bar* and *vice versa*. Each array of neighbor indexes for each object is guaranteed to be sorted in ascending order. For a practical example, see the [world map](https://bl.ocks.org/mbostock/4180634) with topological coloring. ### Transforms # topojson.bbox(topology) [<>](https://github.com/topojson/topojson-client/blob/master/src/bbox.js "Source") Returns the computed [bounding box](https://github.com/topojson/topojson-specification#3-bounding-boxes) of the specified *topology* [*x*₀, *y*₀, *x*₁, *y*₁] where *x*₀ is the minimum *x*-value, *y*₀ is the minimum *y*-value, *x*₁ is the maximum *x*-value, and *y*₁ is the maximum *y*-value. If the *topology* has no points and no arcs, the returned bounding box is [∞, ∞, -∞, -∞]. (This method ignores the existing *topology*.bbox, if any.) # topojson.quantize(topology, transform) [<>](https://github.com/topojson/topojson-client/blob/master/src/quantize.js "Source") Returns a shallow copy of the specified *topology* with [quantized and delta-encoded](https://github.com/topojson/topojson-specification#213-arcs) arcs according to the specified [*transform* object](https://github.com/topojson/topojson-specification/blob/master/README.md#212-transforms). If the *topology* is already quantized, an error is thrown. See also [topoquantize](#topoquantize). If a quantization number *n* is specified instead of a *transform* object, the corresponding transform object is first computed using the bounding box of the topology. In this case, the quantization number *n* must be a positive integer greater than one which determines the maximum number of expressible values per dimension in the resulting quantized coordinates; typically, a power of ten is chosen such as 1e4, 1e5 or 1e6. If the *topology* does not already have a *topology*.bbox, one is computed using [topojson.bbox](#bbox). # topojson.transform(transform) [<>](https://github.com/topojson/topojson-client/blob/master/src/transform.js "Source") If the specified [*transform* object](https://github.com/topojson/topojson-specification/blob/master/README.md#212-transforms) is non-null, returns a [point *transform* function](#_transform) to remove delta-encoding and apply the transform. If the *transform* is null, returns the identity function. # topojson.untransform(transform) [<>](https://github.com/topojson/topojson-client/blob/master/src/untransform.js "Source") If the specified [*transform* object](https://github.com/topojson/topojson-specification/blob/master/README.md#212-transforms) is non-null, returns a [point *transform* function](#_transform) to apply quantized delta-encoding and remove the transform. If the *transform* is null, returns the identity function. See also [topojson.quantize](#quantize). # transform(point[, index]) Applies this transform function to the specified *point*, returning a new point with the transformed coordinates. If the specified *index* is truthy, the input *point* is treated as relative to the previous point passed to this transform, as is the case with delta-encoded arcs. ## Command Line Reference ### topo2geo # topo2geo [options…] <name=file>… [<>](https://github.com/topojson/topojson-client/blob/master/bin/topo2geo "Source") Converts one or more TopoJSON objects from an input topology to one or more GeoJSON features. For example, to convert the “states” TopoJSON GeometryCollection object in us.json to a GeoJSON feature collection in us-states.json: ``` topo2geo states=us-states.json < us.json ``` For convenience, you can omit the object name and specify only the file *name*; the object name will be the basename of the file, with the directory and extension removed. For example, to convert the “states” TopoJSON GeometryCollection object in us.json to a GeoJSON feature collection in states.json: ``` topo2geo states.json < us.json ``` See also [geo2topo](https://github.com/topojson/topojson/blob/master/README.md#geo2topo). To list the available object names, use [--list](#topo2geo_list). # topo2geo -h
# topo2geo --help Output usage information. # topo2geo -V
# topo2geo --version Output the version number. # topo2geo -n
# topo2geo --newline-delimited Output [newline-delimited JSON](http://ndjson.org/), with one feature per line. # topo2geo -i file
# topo2geo --in file Specify the input TopoJSON file name. Defaults to “-” for stdin. # topo2geo -l
# topo2geo --list List the names of the objects in the input topology, and then exit. For example, this: ``` topo2geo -l < us.json ``` Will output this: ``` counties states nation ``` ### topomerge # topomerge [options…] <target=source> [file] [<>](https://github.com/topojson/topojson-client/blob/master/bin/topomerge "Source") Merges polygons (or meshes lines) from the specified *source* TopoJSON geometry collection object, assigning to the *target* object. See also [topojson.mergeArcs](#mergeArcs) and [topojson.meshArcs](#meshArcs). # topomerge -h
# topomerge --help Output usage information. # topomerge -V
# topomerge --version Output the version number. # topomerge -o file
# topomerge --out file Specify the output TopoJSON file name. Defaults to “-” for stdout. # topomerge -k expression
# topomerge --key expression Specify a JavaScript *expression*, given a TopoJSON geometry object *d* and its zero-based index *i* in its parent collection, that determines how geometry objects are grouped before merging; each group is merged separately. For example, given a topology of U.S. *counties*, where the *id* of each county is it’s five-digit FIPS code, the county boundaries can be merged into state boundaries by using the first two digits of the county FIPS code, which represents the state FIPS code: ``` topomerge states=counties -k 'd.id.slice(0, 2)' < us-counties.json > us-states.json ``` If a key is not specified, all input geometry objects will be merged together. For example, this can be used to merge the state boundaries into a single nation boundary: ``` topomerge nation=states < us-states.json > us.json ``` # topomerge -f expression
# topomerge --filter expression Specify a JavaScript *expression* that filters the input geometries before merging or meshing. In conjunction with [--mesh](#topomerge_mesh), the *expression* is given two TopoJSON geometry objects *a* and *b* that represent the adjacent features for a given arc segment; if the *expression* evaluates truthily, the associated arc segment is retained in mesh. Otherwise, the *expression* is given an input TopoJSON geometry object *d* and its zero-based index *i* in its parent collection; if the *expression* evaluates truthily, the geometry object is retained in the merged polygon. # topomerge --mesh Use [topojson.meshArcs](#meshArcs) instead of [topojson.mergeArcs](#mergeArcs), generating a geometry collection of lines rather than polygons. ### topoquantize # topoquantize [options…] <n> [file] [<>](https://github.com/topojson/topojson-client/blob/master/bin/topoquantize "Source") Quantizes the coordinates of the input TopoJSON topology and [delta-encodes](https://github.com/topojson/topojson-specification#213-arcs) the topology’s arcs. The quantization parameter *n* must be a positive integer greater than one, and determines the maximum expressible number of unique values per dimension in the resulting quantized coordinates; typically, a power of ten is chosen such as 1e4, 1e5 or 1e6. If the *topology* does not already have a [bbox](#bbox), one is computed and assigned. If the *topology* is already quantized, an error is thrown. See also [topojson.quantize](#quantize). # topoquantize -h
# topoquantize --help Output usage information. # topoquantize -V
# topoquantize --version Output the version number. # topoquantize -o file
# topoquantize --out file Specify the output TopoJSON file name. Defaults to “-” for stdout.