> For the complete documentation index, see [llms.txt](https://docs.earthindex.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.earthindex.ai/search/reference-layers.md).

# Reference layers

Upload your own GeoJSON as a reference layer for context while labelling, turn its features into labels, and fix uploads that fail.

A reference layer is geospatial data you upload to give context while you label. Typical examples are roads, train lines or hospitals, protected-area or Indigenous land boundaries, and datasets from earlier surveys.

## Before you start

* Use a GeoJSON file. Most GIS tools export it, and you can check yours at [geojson.io](https://geojson.io/).
* Keep the file under 10 MB. The upload form accepts up to 12 MB, but the server rejects anything over 10 MB.
* Use longitude and latitude in WGS 84 (EPSG:4326). Longitude must be between -180 and 180, and latitude between -90 and 90.
* A project holds 1 reference layer with Open access or 5 with Full Access. See [Limits and quotas](https://docs.earthindex.ai/reference/limits-and-quotas.md).

## Steps

1. Open your project and select the layers button in the toolbar. The **Map Layers** panel opens.

   ![The map layers panel opened from the layers button in the toolbar.](https://182773137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIQB2eToY1Iv2IH6cERjn%2Fuploads%2Fgit-blob-0dfac121b3595f15913c8b71879f88fbf5b99397%2Fcoordinates.jpg?alt=media)
2. Find the **Reference Layers** section of the panel.

   ![The reference layers section of the layers panel.](https://182773137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIQB2eToY1Iv2IH6cERjn%2Fuploads%2Fgit-blob-0dfac121b3595f15913c8b71879f88fbf5b99397%2Fcoordinates.jpg?alt=media)
3. Select **New Reference Layer**.

   ![The new reference layer menu with the upload option.](https://182773137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIQB2eToY1Iv2IH6cERjn%2Fuploads%2Fgit-blob-f54d586deedfb25985cf55317c6b48fcbe2bf55d%2Fnew-reference-layer-menu.jpg?alt=media)
4. Select **Upload**, then choose the GeoJSON file on your computer.
5. Wait while the layer shows "Loading layer...". The app prepares the file for display on the web, which takes a short while.

Some accounts also show **Search for Stuff** in the menu. It builds a layer from open data with AI search, for example for solar farms or quarries.

## Manage a layer

Each layer in the panel has these controls:

* Name: select the name to rename the layer in place.
* Color: select the color swatch and pick a new color.
* **Hide Layer** or **Show Layer**: select the eye icon to hide the layer without removing it.
* **More actions**: the three-dot menu has **Focus layer**, **Convert to positive labels**, **Convert to negative labels** and **Delete layer**.

The name and color save with your project and show if you make the project public. You cannot edit the features or geometries you upload.

**Delete layer** asks you to confirm in the **Delete Reference Layer** dialog. A deleted layer comes back only if you upload the file again.

## Label from a layer

A layer of known examples lets you label many tiles without checking each one. Open **More actions** on the layer and select **Convert to positive labels**. Every grid cell that overlaps a feature becomes a positive label. Select **Convert to negative labels** to mark them as negatives instead.

Conversion adds labels only up to your limit for labels per layer. See [Limits and quotas](https://docs.earthindex.ai/reference/limits-and-quotas.md).

For example, you upload a 2017 dataset of known chicken farm buildings and convert it to positive labels. A search can then find new buildings that the dataset does not include, such as a farm complex built after 2017.

## If something goes wrong

| Symptom                                                                                                                  | Fix                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Reference layer file size must be less than 12MB."                                                                      | The file is over 12 MB, and the form checks this before it uploads. Aim for under 10 MB, because files between 10 and 12 MB pass this check and then fail with the next row. Simplify geometries, remove attribute columns you do not need, or split the data into several files. Each file becomes its own layer and counts toward your limit.                                                                                                                                                                            |
| "Error uploading reference layer file."                                                                                  | The most likely causes are a file over 10 MB, coordinates that are not longitude and latitude in WGS 84, or a file that is not GeoJSON. Projected coordinates in metres fail, and so do shapefiles and KML. Open the file in [geojson.io](https://geojson.io/). If the features land in the wrong place or not at all, reproject the data to EPSG:4326 and export it again as GeoJSON. A GeoJSON file is text that starts with `{`. The same message appears if processing fails after the upload, so try uploading again. |
| A yellow message reads "quota exceeded: maximum reference layers per project limit reached", with your limit in brackets | You reached your reference layer limit. Select **More actions** > **Delete layer** on a layer you no longer need, then upload again. You can also combine several datasets into one GeoJSON file under 10 MB. For more layers, request Full Access in [Create an account](https://docs.earthindex.ai/get-started/account.md).                                                                                                                                                                                              |
| The layer keeps showing "Loading layer..."                                                                               | After a while, "Hold tight, extra data crunching needed" appears. Wait for it to clear. If an error message appears instead, use its row above. If the layer never appears and no error shows, reload the project. If it is still missing, upload the file again and report it through the feedback form in [Create an account](https://docs.earthindex.ai/get-started/account.md#get-help).                                                                                                                               |
| "Error converting reference layer to points."                                                                            | Your layer may already be at the limit for labels per layer, or the conversion failed. Try again. If it keeps failing, check the limit in [Limits and quotas](https://docs.earthindex.ai/reference/limits-and-quotas.md).                                                                                                                                                                                                                                                                                                  |
| "Error updating reference layer." or "Error deleting reference layer."                                                   | Try the action again. If the message persists, reload the project and report it through the feedback form.                                                                                                                                                                                                                                                                                                                                                                                                                 |

## Related

* [Label tiles](https://docs.earthindex.ai/search/label-tiles.md)
* [Limits and quotas](https://docs.earthindex.ai/reference/limits-and-quotas.md)
* [Create an account](https://docs.earthindex.ai/get-started/account.md)
