Importing data

Bring in a GeoJSON file from another tool, a spreadsheet with coordinates, a GPS track, or a whole squidmaps map. Everything you import becomes ordinary features that you can style, rename, move and delete like the ones you draw.

Ways to import

Drag and drop

Drag one or more files from your computer onto the editor. The map dims while you’re dragging; let go to import them. Several files are imported one after another, each reviewed on its own.

The map menu

Open the menu under the squid in the top left of the editor and choose Import:

• Import file opens your computer’s file picker. You can also press ⌘ O (Ctrl O on Windows).
• Paste text opens a box to paste data into, such as GeoJSON copied from another site, a column of coordinates, or rows of a CSV. Choose its format below the box.
• From URL downloads a file from the web. The address has to be public, and the server has to allow downloads from other sites (CORS). Files from a URL can be up to 5 MB.

You can also paste features you’ve copied, from squidmaps or as GeoJSON, straight onto the map with ⌘ V. They’re added right away, without a review.

Reviewing an import

Nothing is added to your map until you’ve looked at it. Each import opens a review that shows:

• What’s coming in: how many features, broken down into points, linestrings, polygons and text, on a preview map fitted to them. Hover a feature in the preview to see its properties.
• Names and descriptions: which property becomes each feature’s name (shown in the feature list, in labels and in tooltips) and which becomes its description (shown in its popup). squidmaps picks likely ones, like name, title or label for names and description or notes for descriptions, and you can change them.
• Other properties: everything else in the data. squidmaps doesn’t use other properties, so they’re dropped to keep your map small. The review lists what’s dropped.
• Where the features go: into a new folder, named after the file (you can rename it), or at the top level of the feature list. Either way they’re added after the features already on the map.

Some things happen on every import:

• Features without geometry are left out, and the review says how many.
• Coordinates are rounded to six decimal places, about 11 cm.
• squidmaps’ own properties, like @fill or @popup, are kept, so features styled in squidmaps keep their look and their tooltips and popups. Ones that aren’t valid are dropped. See the map specification for all of them.
• Features that name a folder in @folder go into that folder, reusing a folder of the same name if the map has one.

Files squidmaps can’t read, like a regular image, say there’s no spatial data in them, and nothing is added.

Supported formats

squidmaps tells most formats apart by their file extension. Text files without a telling extension, like .txt, are recognized by what’s in them: GeoJSON, WKT, coordinates and encoded polylines.

GeoJSON

.geojson or .json. A FeatureCollection, a single Feature, or a bare geometry. Every geometry type works, including MultiPolygons and GeometryCollections.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "name": "Tompkins Square Park", "acres": 10.5 },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-73.98258, 40.72795],
            [-73.97964, 40.72676],
            [-73.97835, 40.72857],
            [-73.98131, 40.72977],
            [-73.98258, 40.72795]
          ]
        ]
      }
    },
    {
      "type": "Feature",
      "properties": { "name": "Ninth Street Espresso" },
      "geometry": { "type": "Point", "coordinates": [-73.98163, 40.72654] }
    }
  ]
}

Here the park is named from name, and acres is dropped.

GeoJSON can carry squidmaps styling, so features look the way you want as soon as they’re imported:

{
  "type": "Feature",
  "properties": {
    "name": "Ninth Street Espresso",
    "description": "**Great** cortados.",
    "@point-type": "marker",
    "@marker-disc": "#D9664E",
    "@marker-icon": "solid/mug-hot",
    "@popup": "card",
    "@folder": "Coffee"
  },
  "geometry": { "type": "Point", "coordinates": [-73.98163, 40.72654] }
}

squidmaps maps

A whole map, as downloaded from Export → Map (.json) in the map menu. It’s a JSON document with the map’s name, description, basemap, extent, legend and features (see the map spec).

{
  "name": "Coffee in the East Village",
  "description": "Where I drink coffee.",
  "basemap": { "type": "SQUIDMAPS", "style": "light", "opacity": 1, "labelVisibility": true },
  "extent": { "zoom": { "mode": "range", "min": 0, "max": 22 }, "bounds": null, "initialBounds": null },
  "view": null,
  "legend": null,
  "features": [
    {
      "type": "Feature",
      "id": "f1",
      "properties": { "name": "Ninth Street Espresso", "@folder": "Coffee" },
      "geometry": { "type": "Point", "coordinates": [-73.98163, 40.72654] }
    }
  ]
}

When you import a map, the review asks what to do with it:

• Add its features to the map you’re editing, with their styles, labels and popups. The other map’s basemap, details and legend aren’t used.
• Replace this map with it: its features, folders, basemap, name, description, extent and legend all replace this map’s. squidmaps warns you first and asks you to confirm. Your published map doesn’t change until you publish again.

TopoJSON

.topojson, or .json with "type": "Topology". Each object in the topology becomes features.

{
  "type": "Topology",
  "objects": {
    "places": {
      "type": "GeometryCollection",
      "geometries": [
        { "type": "Point", "coordinates": [-73.98163, 40.72654], "properties": { "name": "Ninth Street Espresso" } }
      ]
    }
  },
  "arcs": []
}

GeoJSONL

.geojsonl, .geojsons or .ld: newline-delimited GeoJSON, one feature per line.

{"type":"Feature","properties":{"name":"Ninth Street Espresso"},"geometry":{"type":"Point","coordinates":[-73.98163,40.72654]}}
{"type":"Feature","properties":{"name":"Abraço"},"geometry":{"type":"Point","coordinates":[-73.98793,40.72636]}}

CSV and TSV

.csv or .tsv. Each row with a location becomes a feature. The review has a Locations section to choose:

• the delimiter: comma, semicolon or tab
• how rows have their locations, and which columns hold them

squidmaps looks at the column names to guess these, and the preview updates as you change them. Rows without a location are left out.

Longitude and latitude columns become points. Columns named like lon, lng, longitude, lat and latitude are found automatically.

name,latitude,longitude
Ninth Street Espresso,40.72654,-73.98163
Abraço,40.72636,-73.98793
Tompkins Square Park,40.72637,-73.98172

A WKT column holds each row’s geometry as Well-Known Text:

name,wkt
Ninth Street Espresso,"POINT (-73.98163 40.72654)"
Avenue B,"LINESTRING (-73.98306 40.72165, -73.97741 40.72944)"

A GeoJSON column holds each row’s geometry as GeoJSON:

name,geojson
Ninth Street Espresso,"{""type"":""Point"",""coordinates"":[-73.98163,40.72654]}"

An encoded polyline column holds each row’s line as an encoded polyline:

name,polyline
Route,"evnjG~skwJr`x\yhga@dhvTpoxe@|feU_po`@"

ZIP codes place each row at the center of its US ZIP code:

name,zip
Main office,10009
Warehouse,11211

H3 cells become each H3 cell’s hexagon:

name,h3
Block,892a100d2c3ffff

Excel spreadsheets

.xls or .xlsx. They’re read like CSV, with a choice of sheet instead of a delimiter. The first row is the column names.

KML and KMZ

.kml, from Google Earth, Google My Maps and many other tools, or .kmz, a zipped KML. Placemarks become features, named from their <name> and described from their <description>.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
    <Placemark>
      <name>Ninth Street Espresso</name>
      <description>Great cortados.</description>
      <Point><coordinates>-73.98163,40.72654</coordinates></Point>
    </Placemark>
  </Document>
</kml>

GPX

.gpx, from GPS devices and apps like Strava. Waypoints become points, and tracks and routes become lines.

<?xml version="1.0" encoding="UTF-8"?>
<gpx version="1.1" creator="example" xmlns="http://www.topografix.com/GPX/1/1">
  <wpt lat="40.72654" lon="-73.98163"><name>Coffee stop</name></wpt>
  <trk>
    <name>Morning walk</name>
    <trkseg>
      <trkpt lat="40.72165" lon="-73.98306"/>
      <trkpt lat="40.72637" lon="-73.98172"/>
      <trkpt lat="40.72944" lon="-73.97741"/>
    </trkseg>
  </trk>
</gpx>

TCX

.tcx, the Training Center format from Garmin devices. Activities and courses become lines.

<?xml version="1.0" encoding="UTF-8"?>
<TrainingCenterDatabase xmlns="http://www.garmin.com/xmlschemas/TrainingCenterDatabase/v2">
  <Courses>
    <Course>
      <Name>Loop</Name>
      <Track>
        <Trackpoint><Position><LatitudeDegrees>40.72165</LatitudeDegrees><LongitudeDegrees>-73.98306</LongitudeDegrees></Position></Trackpoint>
        <Trackpoint><Position><LatitudeDegrees>40.72944</LatitudeDegrees><LongitudeDegrees>-73.97741</LongitudeDegrees></Position></Trackpoint>
      </Track>
    </Course>
  </Courses>
</TrainingCenterDatabase>

Shapefiles

A shapefile is several files with the same name. Import them together, either as a .zip or by selecting or dropping all of them at once:

parcels.shp   the shapes (required)
parcels.shx   an index of the shapes
parcels.dbf   each shape's attributes
parcels.prj   the coordinate system

Without a .dbf, features come without attributes, so there’s nothing to name them from. Without a .prj, coordinates are read as longitude and latitude. The review notes either.

FlatGeobuf

.fgb, a fast binary format that tools like QGIS and GDAL write. It’s read like GeoJSON. Being binary, there’s no text sample to show.

WKT

Well-Known Text, one geometry per line, from databases like PostGIS. Paste it as text, or import a .txt file.

POINT (-73.98163 40.72654)
LINESTRING (-73.98306 40.72165, -73.98172 40.72637, -73.97741 40.72944)
POLYGON ((-73.98258 40.72795, -73.97964 40.72676, -73.97835 40.72857, -73.98131 40.72977, -73.98258 40.72795))

Encoded polylines

Google’s encoded polyline format, as directions and routing services return lines, one per line. Paste it as text, or import a .txt file.

evnjG~skwJr`x\yhga@dhvTpoxe@|feU_po`@

Coordinates

Decimal coordinates, one point per line. Paste them as text and choose whether longitude or latitude comes first.

-73.98163, 40.72654
-73.98793, 40.72636

Bounding boxes

A box as four numbers, west, south, east, north, as many tools and APIs give extents. Paste it as text and choose BBOX as its format. It becomes a rectangle.

-74.0259, 40.6829, -73.9067, 40.8794

OpenStreetMap XML

.osm or .xml, as exported from openstreetmap.org or Overpass. Nodes with tags become points, and ways become lines or polygons.

<?xml version="1.0" encoding="UTF-8"?>
<osm version="0.6">
  <node id="1" lat="40.72654" lon="-73.98163">
    <tag k="name" v="Ninth Street Espresso"/>
    <tag k="amenity" v="cafe"/>
  </node>
</osm>

GTFS shapes

A transit feed’s shapes.txt, from a GTFS feed. Each shape becomes a line.

shape_id,shape_pt_lat,shape_pt_lon,shape_pt_sequence
M15,40.72165,-73.98306,1
M15,40.72637,-73.98172,2
M15,40.72944,-73.97741,3

GeoTIFF

.tif or .tiff. squidmaps doesn’t show imagery, so a GeoTIFF becomes a polygon outlining the area the image covers.

Photos

.jpg or .jpeg photos with a location in their EXIF data, as most phones record. Each photo becomes a point where it was taken. Photos without a location have no spatial data to import.