# Spreadsheets

<figure><img src="https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2FCY0Dmflq0H8eifcabuuR%2Fspreadsheet.png?alt=media&#x26;token=907591c3-f90f-4582-bd08-5a1d8015549c" alt="" width="563"><figcaption></figcaption></figure>

Tabular data such as spreadsheets can reference geography in many forms: explicitly with lat/lon points and geometries, or implicitly with zip codes, place names, or street addresses. When you upload a spreadsheet, Felt uses AI to identify the geometry columns in your data and depending on the type of geometry will either use Geocoding or Geomatching.

## Geocoding

Sometimes, our data doesn’t have explicit coordinates, such as latitudes and longitudes. Instead, we might have *implicit* geospatial data, such as names of street addresses. *Geocoding* is the process of converting address data into points.

To visualize address data make sure your fields have appropriate names, then drag and drop your spreadsheet or CSV directly into a map!

{% hint style="info" %}
By default, Felt will geocode address data for up to 10,000 addresses per upload. If you need a higher limit, [contact sales](https://felt.com/sales) to upgrade to our [Enterprise plan](https://felt.com/pricing).
{% endhint %}

### Preparing address data

Address fields should be given easy-to-find names, such as:

* <mark style="color:red;">`address`</mark> for single fields with complete address
* <mark style="color:red;">`number`</mark> & <mark style="color:red;">`street`</mark> for house numbers and street names
* <mark style="color:red;">`city`</mark> or <mark style="color:red;">`locality`</mark> for place names
* <mark style="color:red;">`zip`</mark> for postal code
* <mark style="color:red;">`state`</mark>, <mark style="color:red;">`region`</mark>, or <mark style="color:red;">`province`</mark> for first-order administrative divisions like U.S. states
* <mark style="color:red;">`country`</mark> for countries

### Reviewing accuracy

Geocoding isn’t a perfect process. Much like a search engine, sometimes you might not find exactly what you’re looking for, depending on both your input and the data that’s available.

Fortunately, Felt lets you review the quality of your geocoding upload, and also download the results so you can fine-tune your input if needed.

You can toggle the Geocoding Results any time you want from the table view by clicking "See full report" in the **`Found`** column and even download the results to fix issues and reupload.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2FTTzHGDG7GEVumNlNN6qN%2FScreen%20Recording%202025-02-27%20at%207.56.28%E2%80%AFPM.mp4?alt=media&token=306ee53b-52be-40e3-95fb-ccd12a935ba7>" %}

## Geomatching

Tables often reference countries, states, zip codes or other regions without including the geometry themselves. Historically, you’d have to join this data with other datasets to work with it on a map. Felt does this automatically with **Geomatching**.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2Fgx43dWfkKecX5GeUO9sf%2FScreen%20Recording%202025-02-27%20at%207.25.09%E2%80%AFPM.mp4?alt=media&token=9852f4bd-d6dd-4f16-bd25-3326996c4b21>" %}

### Available geomatching regions

Data will be checked for the geographic regions listed below and converted to polygon geometries when possible. Optionally, hints present in the column name can be used to choose among valid matches, such as “zip” used to name a column of U.S. ZIP codes.

<table data-full-width="false"><thead><tr><th></th><th width="233">Source</th><th>Example Values</th><th>Column Name Hints</th></tr></thead><tbody><tr><td><strong>Countries</strong></td><td><a href="https://www.naturalearthdata.com/blog/admin-0-countries-point-of-views/">Natural Earth Admin 0</a> United States point of view</td><td>Names: <mark style="color:red;"><code>United States, Ukraine</code></mark> <br>ISO 3166-1 alpha-2 codes: <mark style="color:red;"><code>US, UA</code></mark> <br>ISO 3166-1 alpha-3 codes: <mark style="color:red;"><code>USA, UKR</code></mark></td><td><mark style="color:red;"><code>country, nation, adm0, admin0, admin-0</code></mark></td></tr><tr><td><strong>Global First-Order Admin Areas</strong></td><td><a href="https://www.naturalearthdata.com/downloads/10m-cultural-vectors/10m-admin-1-states-provinces/">Natural Earth Admin 1</a> States, provinces, etc.</td><td>Names: <mark style="color:red;"><code>California, Kiev</code></mark> <br>ISO 3166-2 codes: <mark style="color:red;"><code>US-CA, UA-32</code></mark> <br>Admin-1 codes: <mark style="color:red;"><code>USA-3521, UKR-321</code></mark></td><td><mark style="color:red;"><code>state, province, adm1, admin1, admin-1</code></mark></td></tr><tr><td><strong>Global Time Zones</strong></td><td><a href="https://github.com/evansiroky/timezone-boundary-builder">OSM Timezone Boundary Builder</a></td><td>Names: <mark style="color:red;"><code>America/Los_Angeles, Europe/Kyiv</code></mark></td><td><mark style="color:red;"><code>tz, tzinfo, timezone, time zone</code></mark></td></tr><tr><td><strong>EU Statistical Units (NUTS 1)</strong></td><td><a href="https://ec.europa.eu/eurostat/web/gisco/geodata/reference-data/">Eurostat GISCO Reference Data</a></td><td>Names: <mark style="color:red;"><code>Thüringen, Αττική</code></mark> <br>NUTS codes: <mark style="color:red;"><code>DEG, EL3</code></mark></td><td><mark style="color:red;"><code>state, province, region, nuts</code></mark></td></tr><tr><td><strong>EU Statistical Units (NUTS 2)</strong></td><td><a href="https://ec.europa.eu/eurostat/web/gisco/geodata/reference-data/">Eurostat GISCO Reference Data</a></td><td>Names: <mark style="color:red;"><code>Lazio, Θεσσαλία</code></mark> <br>NUTS codes: <mark style="color:red;"><code>ITI4, EL61</code></mark></td><td><mark style="color:red;"><code>state, province, region, nuts</code></mark></td></tr><tr><td><strong>EU Statistical Units (NUTS 3)</strong></td><td><a href="https://ec.europa.eu/eurostat/web/gisco/geodata/reference-data/">Eurostat GISCO Reference Data</a></td><td>Names: <mark style="color:red;"><code>Eure-et-Loir, Essex Thames Gateway</code></mark> <br>NUTS codes: <mark style="color:red;"><code>FRB02, UKH37</code></mark></td><td><mark style="color:red;"><code>state, province, region, nuts</code></mark></td></tr><tr><td><strong>EU Local Admin. Units (LAU)</strong></td><td><a href="https://ec.europa.eu/eurostat/web/gisco/geodata/reference-data/">Eurostat GISCO Reference Data</a></td><td><p>Names: <mark style="color:red;"><code>Eggendorf im Traunkreis,Čejč LAU codes: AT_41004, 586099 GISCO</code></mark> </p><p>codes: <mark style="color:red;"><code>AT_41004, CZ_586099</code></mark></p></td><td><mark style="color:red;"><code>municipio, municipality, commune, comuni, gemeinde, lau</code></mark></td></tr><tr><td><strong>US States</strong></td><td><a href="https://www2.census.gov/geo/tiger/TIGER2022/STATE/tl_2022_us_state.zip">U.S. Census 2022 boundary file</a></td><td>Names: <mark style="color:red;"><code>California, New York</code></mark><br>Postal codes: <mark style="color:red;"><code>CA, NY FIPS</code></mark> codes: <mark style="color:red;"><code>06,04000US36, 0400000US48</code></mark></td><td><mark style="color:red;"><code>state</code></mark></td></tr><tr><td><strong>US Counties</strong></td><td><a href="https://www2.census.gov/geo/tiger/TIGER2021/COUNTY/tl_2021_us_county.zip">U.S. Census 2021 boundary file</a></td><td>FIPS codes: <mark style="color:red;"><code>06001, 05000US36061, 0500000US48453</code></mark></td><td><mark style="color:red;"><code>county</code></mark></td></tr><tr><td><strong>US CBSAs</strong></td><td><a href="https://www2.census.gov/geo/tiger/TIGER2021/CBSA/tl_2021_us_cbsa.zip">U.S. Census 2022 boundary file</a></td><td><p>Names: <mark style="color:red;"><code>San Francisco-Oakland-Berkeley, CA, New York-Newark-Jersey City, NY-NJ-PA Metro</code></mark><br>Area FIPS codes: <mark style="color:red;"><code>41860, 33000US35620,</code></mark></p><p><mark style="color:red;"><code>3300000US12420</code></mark></p></td><td><mark style="color:red;"><code>cbsa</code></mark></td></tr><tr><td><strong>US Zip Codes (ZCTAs)</strong></td><td><a href="https://postalpro.usps.com/ZIP_Locale_Detail">USPS ZIP locale detail</a> <a href="https://www2.census.gov/geo/tiger/TIGER2012/ZCTA5/tl_2012_us_zcta510.zip">U.S. Census 2012 boundary file</a> <a href="https://www2.census.gov/geo/tiger/TIGER2022/ZCTA520/tl_2022_us_zcta520.zip">U.S. Census 2022 boundary file</a></td><td>ZIP codes: <mark style="color:red;"><code>94612, 06511</code></mark></td><td><mark style="color:red;"><code>zip, zipcode, postcode</code></mark></td></tr><tr><td><strong>US Census Tracts</strong></td><td><a href="https://www2.census.gov/geo/tiger/TIGER2022/COUNTY/tl_2022_us_county.zip">U.S. Census 2022 boundary file</a></td><td>FIPS codes: <mark style="color:red;"><code>06001402900, 14000US09170141900, 1400000US48453001103</code></mark></td><td><mark style="color:red;"><code>tract</code></mark></td></tr></tbody></table>

### H3 geomatching

{% hint style="success" %}
This feature is only available to customers on the [Enterprise plan](https://felt.com/pricing). To upgrade, [contact sales](https://felt.com/sales).
{% endhint %}

When a spreadsheet contains H3 identifiers, Felt automatically detects and geomatches them to hexagonal cells at the encoded resolution.

#### Supported H3 formats

Felt will automatically detect and process both hexadecimal string (e.g., `8928308280fffff`) and integer (e.g., `613196848522715135`) representations of H3 identifiers.

{% hint style="info" %}
The H3 level detected from your IDs is automatically used as the default resolution for display.
{% endhint %}

To ensure Felt correctly identifies and maps your H3 data:

* Column headers should be clearly labeled (e.g., `h3_id`, `h3_index` )
* H3 indexes should be in standard format without additional characters
* All H3 indexes should be at the same resolution level

If H3 identifiers aren't automatically geomatched:

* Open Geometry settings by clicking the ![](https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2F2TN3Tf1z8vGQByRGJE45%2Fmore.svg?alt=media\&token=9161546c-ebad-46c1-81da-fda42dec3987) icon in the upper right of the [table](https://help.felt.com/layers/table-view)&#x20;
* Select `H3` as the `Area type`, choose the correct `H3 column`, then click `Update spreadsheet`

<figure><img src="https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2FoNdSg3ssdGhbCOM8iK27%2FScreenshot%202025-03-25%20at%205.22.04%E2%80%AFPM.png?alt=media&#x26;token=3f189fa5-63ca-47e9-b67a-6d4e3808b7b9" alt="" width="563"><figcaption></figcaption></figure>

## Changing or selecting a geometry type

Occasionally Felt doesn't automatically detect the columns with spatial data, or the detected spatial column needs to be changed. Fortunately, you can select the most appropriate geometry type after uploading the data into Felt.

Changing the geometry type drawn by Felt allows you to customize the way your data is shown on the map. Making these changes allows you to color-code the data the way you need it displayed.

### Steps

1. Select the layer in the Legend
2. Click **Open table** in the toolbar

<figure><img src="https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2F6moFXGLcE6QMkNdo0UIU%2Fimage.png?alt=media&#x26;token=579163d6-e0b6-40d9-82e4-2a709aa3f6b6" alt="" width="355"><figcaption></figcaption></figure>

3. Click on **Geometry settings** (underneath the ![](https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2F2TN3Tf1z8vGQByRGJE45%2Fmore.svg?alt=media\&token=9161546c-ebad-46c1-81da-fda42dec3987) icon in the upper right of the [table](https://help.felt.com/layers/table-view))

<figure><img src="https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2F5t6OGl5vC7nh9nc9l6BF%2Fgeomatching.png?alt=media&#x26;token=f0ed40f9-33f8-4dfa-94ac-dba4e23c22d5" alt="" width="375"><figcaption></figcaption></figure>

4. Select desired geometry type and columns
5. Click **Update spreadsheet**

<figure><img src="https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2FGiyEm0GbFiumgWf03rfk%2FScreenshot%202025-02-27%20at%207.11.19%E2%80%AFPM.png?alt=media&#x26;token=51842b14-4fc7-4810-be9a-714327019845" alt="" width="563"><figcaption></figcaption></figure>

{% hint style="info" %}
Selecting address columns will result in Geocoding addresses, while country names or ZIP codes will result in Geomatching regions.
{% endhint %}

### Examples

1. Choosing different columns in a spreadsheet to ensure the right location data is used.
2. Change the points on a map to fill up their associated province, state, or zip code region

<figure><img src="https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2FvBAV7iQOhL6dQPY5opeL%2FUntitled.png?alt=media&#x26;token=0e9d9ce3-ae29-48ba-bffb-e4f8c5168450" alt="" width="563"><figcaption></figcaption></figure>

3. Symbolize an area or region as a point instead

<figure><img src="https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2F73Z9ZddADq3Toz6qioch%2FUntitled%201.png?alt=media&#x26;token=b01e41b2-bac4-44b0-a69c-c534d2769607" alt="" width="563"><figcaption></figcaption></figure>

## Best practices

#### Structure your data

* Use one header row with clear column names.&#x20;
* Each row should represent a single geographic feature or location. Avoid duplicate entries for the same location across multiple tabs or spreadsheets. Overlapping points won't add value on the map.
* Remove Excel-specific formatting: strip merged cells, complex excel styling, and calculated fields before uploading. Try pasting only the values of your styled excel sheet into a new sheet and upload that to Felt.&#x20;
* Keep header names consistent if you plan to refresh or update the data later—renaming columns used in styling or filters will break those settings

#### Organize data efficiently

* Consolidate related data into one spreadsheet and use a "category" or "type" column to distinguish between similar items
  * You can filter and style by category in Felt after uploading—different colors and shapes can represent different types
* Use columns strategically: columns should track attributes and metrics you want to visualize, filter, or analyze in Felt (type, category, owner, status, revenue, etc.).&#x20;
  * You can create [components](https://help.felt.com/dashboards-and-components/components) in Felt to filter and interact with column data.
* Use separate spreadsheets when:
  * Tracking entirely different entities (e.g., separate companies or unrelated datasets)
  * Workflows require independent management or separate access permissions of the data

#### Ensure accurate geocoding

* Longitude and latitude coordinates provide the most reliable results. Coordinates are always stable and won't have geocoding errors.
* Provide complete addresses and include street number, street name, city, state, and ZIP code. Incomplete addresses may fail to geocode. Avoid descriptive text in address fields.
* Check the geocoding report after upload to identify failed locations. Look for the chart icon in the table view (next to the "Found" column)

  <figure><img src="https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2FgcMa2c8M1QWEj74RjD0p%2Fimage.png?alt=media&#x26;token=a308e6a0-dcdd-464a-8776-88ab2bc958a0" alt="" width="194"><figcaption></figcaption></figure>
* Download results to see which addresses need correction. Fix issues in your source spreadsheet and use [Upload new version](https://help.felt.com/upload-anything/refreshing-data#file-uploaded-layers) to update the results

#### Refresh data without breaking your map

* Use [Upload new version](https://help.felt.com/upload-anything/refreshing-data#file-uploaded-layers) to refresh data without needing to restyle

  <figure><img src="https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2FrK5UO1OUo8t2WVOwDb36%2Fimage.png?alt=media&#x26;token=ff553911-02e2-473d-9998-7a35b2a9512f" alt="" width="163"><figcaption></figcaption></figure>
* When refreshing, maintain column consistency. Do not rename columns that are used in styling, filters, or components. Felt uses column headers to maintain styling when you upload new versions.&#x20;
* You can add new columns without affecting existing visualizations
* Felt will detect if the column used in styling is no longer available and prompt you to select an updated column for styling consistency

  <figure><img src="https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2FWWFoSDAtxoKyhuvoMHfw%2Fimage.png?alt=media&#x26;token=32b9c0e7-944e-424c-9190-67abb1c06aa8" alt="" width="563"><figcaption></figcaption></figure>

#### Geographic data formats

* Uploads can include geographic data in unprojected decimal degrees latitude and longitude
* Geographic fields should be given easy-to-find names, such as:
  * `geometry`, `wkt`, or `geom_wkt`
  * `x` & `y`
  * `lat` & `lon`, `latitude` & `longitude`, or `lat` & `lng`
* Whole geometries must be in one of these formats:
  * [Well Known Text](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)&#x20;
    * examples: `POINT(-122 37)`, `LINESTRING (-122 37, -123 38)`
  * Hex-encoded Well Known Binary
    * example:`'01010000000000000000805ec00000000000804240'`
  * GeoJSON Geometry Objects&#x20;
    * example: `{'type': 'Point', 'coordinates': (-122.0, 37.0)}`
* Felt can find the location of data using a number of different methods including:&#x20;
  * `Coordinates` and `Addresses` types draw points (see [#geocoding](#geocoding "mention"))&#x20;
  * Provinces, states, zip codes, countries draw areas/polygons (see [#geomatching](#geomatching "mention"))&#x20;
    * `Natural Earth v1`, `US Census, 2020`, and `Eurostat, 2021` types support polygons
  * Latitude & Longitude coordinates
  * `WKT` and `WKB` are more advanced types that can be used for drawing points, lines, or areas.

## Troubleshooting

See the [troubleshooting](https://help.felt.com/upload-anything/troubleshooting "mention") page for common upload failures and how to fix them.