XLSX / CSV import
MapHub imports data from CSV, XLS, XLSX, and ODS files. We recommend XLSX.
Quick start
Say you have a spreadsheet like this:
| address | name |
|---|---|
| 1600 Pennsylvania Ave, Washington | White House |
| 10 Downing Street, London, UK | UK PM Residence |
- Open or create a map.
- Click Import and upload your file.
- MapHub finds the locations and adds them to your map.
Rows that can’t be located go to Unlocated Items — select one and click Place Item to position it manually.
How MapHub locates a row
MapHub checks your columns in this order:
- Coordinates — latitude and longitude columns → placed directly.
- Complete address — a single address column → geocoded.
- Address components — street, city, postal code, etc. → joined and geocoded.
- GeoJSON — a geojson column with geometry data.
The first match applies to the whole file. For example, if your file has both latitude/longitude and address columns, MapHub uses coordinates and skips geocoding.
Rows without a valid location go to Unlocated Items.
Column reference
Column names are matched case-insensitively. Spaces, hyphens, and underscores are treated the same (Postal_Code = postal code).
Names not listed below (like location, place, town) won’t be recognized — rename them to a supported name.
Coordinates
| Field | Recognized names |
|---|---|
| Latitude | lat, latitude |
| Longitude | lng, lon, long, longitude |
Latitude must be −90 to 90, longitude −180 to 180.
Complete address
A single column with the full address. MapHub geocodes each value to find its location.
| Field | Recognized names |
|---|---|
| Complete address | address, addr, full address, street address |
Only this column is geocoded. Other columns like country are not appended automatically. If your addresses need a country, include it in the address text or use the component columns below.
Address components
If your addresses are split across columns, use these names. MapHub joins them and geocodes the result.
| Field | Recognized names |
|---|---|
| House number | house number, house no, street number |
| Street | street |
| City | city |
| State | state, province, region |
| Postal code | postal code, zip, zipcode, zip code, postcode |
| Country | country, country code |
You need street and at least city or a postal code column.
Other columns
| Column | Notes |
|---|---|
title or name | Item title |
description or desc | Item description (Markdown supported) |
group | Group name (see Groups below) |
url | Link URL |
color | Hex color, e.g. #CC1B15 |
visible | true/false or 1/0 |
media_url | e.g. a YouTube video URL |
icon | MapHub icon id (for points) |
label, hide_text | true/false item states |
circle_radius_meters | Positive radius; use with latitude/longitude |
line_width, fill_opacity | Shape styles |
marker_rotation, marker_size, marker_offset_x, marker_offset_y | Custom marker settings |
maphub_image_url | Image reference from a MapHub export |
GeoJSON column
For advanced use, include a column named geojson with a GeoJSON Geometry string:
- Point:
{"type":"Point","coordinates":[-74.00,40.71]} - Polygon:
{"type":"Polygon","coordinates":[[[100.0,0.0],[101.0,0.0],[101.0,1.0],[100.0,1.0],[100.0,0.0]]]} - LineString:
{"type":"LineString","coordinates":[[102.0,0.0],[103.0,1.0],[104.0,0.0],[105.0,1.0]]}
Combining columns in Excel
If your columns have names MapHub doesn’t recognize (like Location or Town), you have two options: rename them to a supported name, or combine them into a new address column.
To combine, say your spreadsheet looks like this:
| A (Location) | B (Town) | C (State) | D (ZIP) | |
|---|---|---|---|---|
| Row 2 | 10 Main St | Boston | MA | 02108 |
Add a new column E called address. In cell E2, type:
=A2 & ", " & B2 & ", " & C2 & ", " & D2
This produces: 10 Main St, Boston, MA, 02108.
Drag the formula down to fill all rows. Then before uploading:
- Select the address column.
- Copy it (Ctrl+C).
- Paste as values (Ctrl+Shift+V) so it becomes plain text, not a formula.
Now upload the file and MapHub will geocode the addresses.
In Google Sheets, use Edit → Paste special → Values only.
Tip: If your data has postal codes with leading zeros (like
02108), format that column as Text in Excel before entering values. Otherwise Excel may drop the leading zero.
Groups
Browser imports place items under Imported from <filename>.
Use this format in the group column for nested groups:
North America／United States／California／Los Angeles
Note: use exactly this ／ character (not a normal /). Copy and paste it.
Sample: Multi-level group sample
Re-importing a MapHub export
MapHub exports include longitude, latitude, and geojson columns, even when empty. If you want to re-import for address geocoding, delete the longitude and latitude columns first. Otherwise MapHub uses coordinate mode and skips geocoding.
API imports don’t geocode — provide coordinates or GeoJSON directly.
Sample files
Download a sample from this map (click Download → Excel XLSX or CSV):
The museums.csv sample has Name, Description, and Address columns. Each address includes the country (e.g. “Rue de Rivoli, 75001 Paris, France”) — download it to try.
Credits
Address geocoding uses your monthly credits. See Search and geocoding — Credits for pools, limits, and what to do when credits run out.
Importing latitude/longitude coordinates does not use credits.