> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapxagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Uploading and Preparing Your Location Data in MapX

> Learn how to upload CSV, GeoJSON, and Excel files to MapX. Covers automatic location column detection, column naming tips, and fixing common import errors.

MapX accepts **CSV, GeoJSON, Excel, GeoTIFF, Shapefile, and text documents**
(TXT, Markdown, Word, and PDF). **CSV, GeoJSON, and Excel** are
general-purpose data formats — they carry attributes and location columns that
MapX auto-detects. **GeoTIFF and Shapefile** are GIS-specific formats: GeoTIFF
is rendered as a raster image layer on the map, and Shapefile is converted to a
vector layer (points, lines, or polygons). **Text and document files** do not
become map layers — MapX reads them as source material the AI can analyze, for
example when generating a report. When you upload a tabular file, MapX scans it
automatically, identifies the columns that contain location information, and
renders your data on the map canvas within seconds.

## Supported File Formats

| Format | Extension | Notes |
| - | - | - |
| **CSV** | `.csv` | Latitude/longitude columns are auto-detected by header name. Address columns are supported and geocoded automatically on Basic plans and above. |
| **GeoJSON** | `.geojson`, `.json` | Point, LineString, and Polygon geometry types are all supported. Properties are imported as attribute columns available for styling and filtering. |
| **Excel** | `.xlsx`, `.xls` | The first sheet is imported. Latitude/longitude or address columns are auto-detected using the same rules as CSV. Additional sheets are ignored. |
| **GeoTIFF** | `.tif`, `.tiff` | GIS-specific. Uploaded as a raster image layer on the map. |
| **Shapefile** | `.shp/.shx/.dbf` (+ optional `.prj`, `.cpg`, etc.), or `.zip` | GIS-specific. Select all files with the same prefix, or upload a zip. Missing `.prj` is treated as WGS84. |
| **Text / Markdown** | `.txt`, `.md` | Document. Read by the AI for analysis and reports; not rendered as a map layer. |
| **Word** | `.docx` | Document. Read by the AI for analysis and reports; not rendered as a map layer. |
| **PDF** | `.pdf` | Document. Read by the AI for analysis and reports; not rendered as a map layer. |

Large aerial or satellite images (GeoTIFF) render as a smooth, zoomable raster
layer, and you can restyle the color bands on the fly.

## Uploads run in the background

Uploads process in the background and show their progress in the upload queue —
you can keep working while a file converts or imports. When an upload finishes,
MapX zooms the map to fit the new layer.

Paid plans can upload single files up to **20 GB**. Uploads are queued, so you
can add several files at once; each file is processed in order.

## Uploading a Shapefile

A Shapefile is defined by several files that share the same prefix and must be
uploaded together:

* **Required**: `.shp` (geometry), `.shx` (index), `.dbf` (attributes)
* **Optional**: `.prj` (coordinate system), `.cpg` (character encoding), plus
  spatial/attribute index files (`.sbn`, `.sbx`, `.qix`, etc.)

Select all of these files at once — MapX groups them into a single upload and
shows an error if a required file is missing. You can also package the files
into a `.zip` and upload that. If the `.prj` file is absent, MapX assumes WGS84
(EPSG:4326); attribute encoding is read from `.cpg` when present. The geometry
is reprojected to WGS84 and added to the map as a regular vector layer.

## How Auto-Detection Works

When you upload a file, MapX performs the following steps before displaying your data:

1. **Header scan** — MapX reads the column names and checks them against a built-in list of common location field names (see [Column Naming Tips](#column-naming-tips) below).
2. **Value inspection** — For candidate columns, MapX samples up to 100 rows to confirm that the values look like valid coordinates (decimal degrees in the range −180 to 180 for longitude, −90 to 90 for latitude).
3. **Confidence preview** — MapX shows you the detected columns and a small sample of matched rows before import completes. You can confirm the detection or manually reassign columns if needed.
4. **Map render** — Once confirmed, all rows with valid coordinates are plotted on the map. Rows with missing or invalid coordinates are skipped, and a count of skipped rows is shown in the import summary.

## Column Naming Tips

For the fastest and most reliable auto-detection, use one of the following standard column names in your file:

**Latitude:**

* `lat`
* `latitude`
* `y`
* `y_coord`
* `lat_dd`

**Longitude:**

* `lng`
* `lon`
* `long`
* `longitude`
* `x`
* `x_coord`
* `lng_dd`

**Address (geocoded automatically on Basic and above):**

* `address`
* `full_address`
* `street_address`
* `location`

## Handling Messy Data

<Accordion title="My lat/lng columns have unusual names">
  If MapX does not automatically detect your coordinate columns, you can map them manually during the import preview step. Click **Edit column mapping**, then use the dropdowns to assign which column represents latitude and which represents longitude. Your custom mapping is saved for the project — if you re-upload the same file, MapX will remember the mapping.

  For bulk workflows or repeated uploads, renaming your columns to one of the standard names listed above is the most reliable long-term solution.
</Accordion>

<Accordion title="Some rows have missing coordinates">
  Rows where the latitude or longitude value is blank, `null`, `N/A`, or outside the valid coordinate range (−90 to 90 for lat, −180 to 180 for lng) are automatically skipped during import. The import summary panel shows the total number of skipped rows and lets you download a CSV of the problematic rows so you can investigate and re-upload.

  Missing coordinates do not cause the import to fail — MapX simply plots the rows it can and reports what was skipped.
</Accordion>

<Accordion title="My addresses aren't coordinates">
  MapX supports address-based geocoding (converting a street address to lat/lng) on the **Basic, Pro, and Business** plans. If your file contains an address column instead of numeric coordinates, MapX will detect it and offer to geocode the column automatically before rendering the map.

  Geocoding uses the column names listed in the [Column Naming Tips](#column-naming-tips) section. Each address lookup counts as one AI prompt against your monthly allowance. Free plan users can manually convert addresses to coordinates using a free tool like [geocod.io](https://geocod.io) or Google Sheets before uploading.
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.