Importing addresses from a spreadsheet

MapHub can geocode addresses when you import a CSV or Excel spreadsheet in the map editor. Supported spreadsheet formats are XLS, XLSX, and ODS. You do not need to convert addresses to coordinates first.

The MapHub API does not geocode table imports. When you use the API, provide latitude and longitude or inline GeoJSON for located items. Rows without source geometry are imported under Unlocated Items.

For an optional manual workflow, see Geocoding using Google Earth.

Choose one location option

MapHub checks the file headers in this order. The first matching option applies to the complete file.

1. Coordinates. Use both a latitude and a longitude column. MapHub does not geocode any row in this mode.
2. Complete address. Use one column that contains each complete address.
3. Address components. Use a street column and at least one city or postal-code column.

If no option matches, MapHub imports every row without a location.

Coordinate headers

Each row needs finite, in-range coordinates. Latitude must be from -90 to 90. Longitude must be from -180 to 180. An invalid coordinate row stays unlocated. It does not fall back to address data.

Complete-address headers

MapHub uses only the trimmed value in this column. It does not append country or other component columns. For example, the museums.csv sample has Address and Country. Complete-address mode wins, so MapHub queries only Address and ignores Country for geocoding.

Note

Combine address columns in Excel

Create an Address column and use TEXTJOIN. For example, if columns B through E contain street, city, state, and postal code, enter this formula in the first data row and fill it down:

=TEXTJOIN(", ",TRUE,B2,C2,D2,E2,"USA")

This produces a value such as 10 Main Street, Boston, MA, 02108, USA. Save the calculated values in the XLSX file before uploading it.

Component headers

MapHub joins nonblank values in this format:

house number street, city, state postal code, country

For example, 10, Main Street, Boston, MA, 02108, and USA become 10 Main Street, Boston, MA 02108, USA. Blank segments are omitted. Each row still needs a street and either a city or postal code.

Only exactly equal adjacent component values are deduplicated after normalization. One value is not removed because it is part of another value. Values such as n/a, unknown, and tbd are not blank.

How headers are matched

MapHub case-folds each header, trims it, replaces underscores, hyphens, and whitespace runs with one space, and removes trailing ., :, or ;. For example, Postal_Code, postal-code, and POSTAL CODE all become postal code.

Matching is exact. Headers such as town, location, place, locality, municipality, district, and suburb are not address aliases. MapHub does not inspect cell contents to guess a field.

If several columns match the same field, MapHub uses the leftmost matching column and ignores later matches.

Import the file

1. Open or create a map.
2. Open Import and upload the CSV, XLS, XLSX, or ODS file.
3. If MapHub asks for confirmation for a large set of unique addresses, confirm the import.

MapHub sends each unique usable address to Amazon Location Service and uses its AWS Stored geocoding mode. This is an external AWS service, not an internal MapHub geocoder. Address imports require configured AWS credentials and consume the map owner’s monthly geocoding allowance. Existing valid circle or inline GeoJSON geometry takes precedence for its row. MapHub places the imported table under Imported from <filename>. A blank, incomplete, overlong, invalid, or unresolved location does not remove the row. MapHub preserves it under Unlocated Items within that import group, including its original address values, so you can place it later.

The 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. MapHub checks the combined map when it is saved and reports when it limits an uploaded table.

If MapHub reports that no address columns were found, rename the headers to one of the exact options above and upload the file again.

CSV and XLSX exports always contain longitude and latitude headers. If you prepare an address-only table from an export, delete both columns before upload. Otherwise, their headers select coordinate mode and MapHub does not geocode the addresses, even when the coordinate cells are blank.

See the table import guide for other supported columns and geometry formats.