XLSX / CSV import

MapHub supports importing data from CSV, XLS, XLSX, and ODS files. We recommend using the XLSX format.

When uploading a table file in the map editor, MapHub tries to identify the file format and locate the geometry data for your items. Browser imports can geocode supported address columns. API table imports never geocode addresses, so API clients must provide coordinates or inline GeoJSON when items need locations.

A browser table import keeps at most the map owner’s full per-map item limit from the uploaded file. Existing map items do not reduce this import-time row limit. The final map save checks the combined map, and the editor reports when it limits an uploaded table.

Specifying item geometry

Valid source circle or inline GeoJSON geometry takes precedence for a row. Otherwise, MapHub uses one location mode for the complete file. It detects that mode from headers only and uses this order:

1. Both latitude and longitude columns: coordinate mode. Address columns are ignored, and no row is geocoded.
2. One complete-address column: complete-address mode. Component columns are ignored for geocoding.
3. A street column and at least one city or postal-code column: component mode.
4. No location mode. Every row is imported without a location.

Location detection never rejects a file because only one coordinate header exists or a row has invalid location values. Every parsed row is preserved. A row without usable source or geocoded geometry is put under the server-generated Unlocated Items group. A grouped row uses an Unlocated Items subgroup under its original direct parent.

To place an unlocated item later, select it under Unlocated Items, click Place Item in the item panel, and click its location on the map. Press Escape to cancel placement. Placing an item keeps it in its current group; save the map to keep the new location.

Addresses

Complete-address columns use these exact headers:

MapHub trims and queries only the complete-address cell. It does not append country or any component. For example, the tutorial museums.csv has Address and Country. Complete-address mode wins, so only Address is used for geocoding.

Note

Combine address columns in Excel

To combine columns B through E into an Address column, enter =TEXTJOIN(", ",TRUE,B2,C2,D2,E2,"USA") in the first data row, fill it down, and save the calculated values before uploading the XLSX file.

Component columns use these exact headers:

Component queries have this order: house number street, city, state postal code, country. Blank segments are omitted. Every component row needs a nonblank street and either a nonblank city or postal code. Only adjacent component values that are exactly equal after normalization are deduplicated. MapHub does not remove a value because it is a substring of another value. Values such as n/a, unknown, and tbd are not blank.

A blank complete address, an incomplete component row, or a query over 200 characters is not sent for geocoding. A provider no-result also leaves the row under Unlocated Items.

MapHub normalizes headers before exact matching. It case-folds and trims each header, replaces underscores, hyphens, and whitespace runs with one space, and strips trailing ., :, and ;. For example, Postal_Code, postal-code, and POSTAL CODE become postal code. It does not use fuzzy matching or cell-content inference. Headers such as location, place, town, locality, municipality, district, and suburb are not supported address aliases.

If several columns match one field, MapHub uses the leftmost matching column in file order. Later matches are ignored. See Importing addresses from a spreadsheet for a task-oriented guide.

Latitude and longitude or geometry

There are two ways to specify an existing location or shape:

1. Latitude and Longitude Columns (for Points)

Use both coordinate columns:

• Latitude: lat or latitude.
• Longitude: lng, lon, long, or longitude.

Each row needs two finite numbers. Latitude must be from -90 to 90, and longitude must be from -180 to 180. A row with a blank, invalid, nonfinite, or out-of-range coordinate stays under Unlocated Items. Coordinate mode does not fall back to address values. If several headers match latitude or longitude, the leftmost one is used.

2. GeoJSON Column (for Points, Polylines, and Polygons)

You can provide geometry directly using inline GeoJSON format within your table. This allows importing points, polylines, and polygons.

• Include a column named geojson.
• The value in this column for each row should be a valid GeoJSON Geometry object string.
  • Example Point: {"type":"Point","coordinates":[-74.00,40.71]}
  • Example Polygon: {"type":"Polygon","coordinates":[[[100.0,0.0],[101.0,0.0],[101.0,1.0],[100.0,1.0],[100.0,0.0]]]}
  • Example LineString (Polyline): {"type":"LineString","coordinates":[[102.0,0.0],[103.0,1.0],[104.0,0.0],[105.0,1.0]]}

Other Columns

These columns provide additional styling and information for your map items (all are optional):

• title or name - the title of the item
• description or desc - the description of the item, Markdown supported
• group - the name of the item’s group. To create multi-level groups please read the section below.
• url - a link URL
• color - hex code for the item’s color, for example #CC1B15
• visible - true/false - if the item is visible (true) or hidden (false). Also accepts 1/0.
• media_url - a media URL, for example a YouTube video.
• icon - a MapHub icon id (for points)
• label, hide_text - true/false item states
• circle_radius_meters - a positive radius; use it with longitude and latitude
• line_width, fill_opacity - shape styles
• marker_rotation, marker_size, marker_offset_x, marker_offset_y - custom marker settings
• maphub_image_url - a same-server image reference from a MapHub spreadsheet export

Export and round trips

CSV and spreadsheet exports use a fixed 21-column schema. Unused cells may be blank; longitude, latitude, and geojson are always included. Optional values are populated only when an item needs them.

Points and labels fill longitude and latitude and leave geojson blank. Circles do the same and also fill circle_radius_meters. Lines and polygons leave both coordinate cells blank and use a compact GeoJSON Geometry string in geojson. Unlocated items leave all three geometry cells blank. Mixed geometry types can share one table.

MapHub selects coordinate mode from headers. Before uploading an address-only version of an exported table, delete its longitude and latitude columns. Otherwise, MapHub does not geocode the address columns, even when all coordinate cells are blank.

Browser address imports send address queries to the external Amazon Location Service using AWS Stored geocoding. They do not use an internal MapHub geocoder. They require configured AWS credentials and consume the map owner’s monthly geocoding allowance. API table imports do not make geocoding requests or consume geocoding allowance.

Images and custom markers use same-server references. Use a MapHub Archive ZIP when you need to move their files to another server. An XLSX cell cannot contain more than 32,767 characters, so MapHub leaves an oversized geometry cell blank. CSV exports the complete geometry.

Spreadsheet import creates new item IDs. It preserves group paths, but it may not preserve group-level or map-level settings. Arbitrary source columns become description lines instead of GeoJSON properties.

Sample data

On the following map, you can click Download / Excel XLSX or CSV to get a sample file demonstrating import using Lat/Lon columns:

XLSX / CSV sample

Multi-level groups

A browser table import places all imported content under Imported from <filename>. Source groups and generated Unlocated Items groups are nested under that import group.

You can create multi-level groups by using the following format in the group column.

North America／United States／California／Los Angeles

Note, you have to use exactly this ／ character. Please copy and paste it. It is not the same as the normal / character.

Have a look at the following sample table: Multi-level group sample