Instant Map

What is Instant Map?

Instant Map is an online mapping tool capable of transforming data of various formats into an interactive map feature. Upload a dataset with location attributes to create an instant visualization of your data, including interactive map markers that display each location's specific attribute values when clicked. Currently, five file formats and two geospatial representations are supported, allowing traditionally non-geospatial file formats to be mapped. Instant Map is a free demonstration of a service that can benefit data analysts, map makers, small business owners, or anyone who needs a complete solution that geocodes, converts, and maps data all with a single click.

How Do I Upload Data?

1. Select the file format of your data:

   • CSV
   • XLSX
   • XML
   • JSON
   • GeoJSON (recommended)
   • Sample
   CSV format must use the comma as a delimiter; fields whose values contain commas must be enclosed in double quotes. XLSX format will map data from only the first worksheet. XML format should contain one parent element, with each dataset item represented by a child element; each dataset item's keys and values must be encoded using attributes. JSON format should contain an array of objects. GeoJSON format is recommended due to its exclusive use of coordinates and default compatibility with mapping software. The Sample option automatically uploads the sample GeoJSON file (15KB).

2. Select the geographic representation present in your data:

   • Address
   • Coordinates (recommended)
   To use Instant Map, each item in your dataset must contain either coordinates (latitude/longitude) or a complete street address. To use addresses, each must be an accurate, complete street address. The address must be located in a field or column at the top level of each item in your dataset and must be titled address. To use coordinates, each pair must consist of two decimals: latitude (-90 to 90) and longitude (-180 to 180). These fields must exist for each item at the top level of each item in your dataset and must be titled latitude and longitude respectively. Because of the limitations in speed and capacity of the free geocoding service used, the address option supports a maximum of 20 items per dataset. If your dataset contains both types of representation, select coordinates. Coordinates are always recommended, as they are cheaper and quicker to map.

3. Click Upload and watch your custom map feature take shape!

Map Interactions

The map can be panned, zoomed, and rotated using keyboard/mouse or touch controls. The navigation control buttons at the top right will also zoom and rotate the map. Once data is imported onto the map, you will see dark markers for each item in your dataset at the correct location. Use the controls at the top left to toggle the icon type between pins and dots. Click on a marker to open a popup window displaying the marker's properties. These correspond to the original fields or columns of the associated item in your dataset. Moving the map will update the URL's path according to zoom level, latitude, and longitude, in that order.

Tech Stack

Instant Map is currently built on software that is either completely free or offers a free plan. The frontend uses React and Tailwind CSS. The frontend and backend are both provided through Next.js and written in TypeScript. Validation and parsing are assisted by the Zod, Papa Parse, SheetJS, and xml-js libraries. The map library used is MapLibre, an open-source fork of Mapbox. Map tiles are generously provided by OpenFreeMap, a free, open-source map tile provider. The geocoding API (converts addresses to coordinates) is powered by the Geoapify free plan. Upstash for Redis is used to assist with rate limiting the geocoding API and tracking daily use limits. Deployment, environment variables, and a cron job that resets the daily geocoding limit are managed through Vercel. Instant Map is open-source, and its source code is available on GitHub. Please feel free to fork the project to make changes, and do not hesitate to raise an issue if unexplained bugs or errors occur.

Why Not Mapbox?

Mapbox is a business-oriented location platform with high customization and versatility. It offers access to a map library, geocoding API, and more through a pay-as-you-go pricing system. Instant Map originally used Mapbox, both for the map feature and geocoding service. Using Mapbox, geocoding was quicker, cheaper, and could comfortably support many more addresses at a time. Their map library also provided useful shortcut features, such as SDF icons. For now, Instant Map has been migrated to free Mapbox alternatives due to issues with Mapbox's terms of service.

Instant Map originally intended to use a proxy server to handle requests generated by the Mapbox map and geocoding. One of the security measures this proxy server offered is being able to hide the Mapbox access token required to call Mapbox APIs. A valid access token must be included in all Mapbox API calls, but this unfortunately introduces a vulnerability. Calling a Mapbox API from the frontend with an access token exposes that token to the frontend users. On any site that directly calls Mapbox API, malicious users can extract the public access token from the Network tab of developer tools, using it to make their own API calls from a REST client like Postman.

Putting the Mapbox access token in the frontend is extremely detrimental to Mapbox's customers for the following reasons: Mapbox forbids the restriction of certain paid services on a token, for example, geocoding. This means users can make unchecked amounts of API calls, which can eventually rack up unwanted charges. Mapbox does not support custom rate limiting either. Specifically, Mapbox does not offer developers any method of restricting a token to be used a certain amount of times, a common-sense feature that would allow smart developers to put a hard cap on the amount of money spent within each billing period.

Instant Map initially solved this problem by proxying Mapbox APIs in order to enforce custom rate limiting, ensuring Mapbox API calls would remain within initial free limits. For example, if Mapbox allows 50,000 free monthly map instantiations before the next ones become paid, then a proxy could cap the number of calls made at 50,000 to guarantee free usage. The problem is that Mapbox prevents proxying any of their APIs in their terms of service, even if the sole reason is to hide the token for security or to set up rate limiting to prevent overuse. Through these restrictions, Mapbox prevents developers from mitigating their pay-as-you-go pricing in any way, even if every API call is accounted for; as a consequence, Instant Map has since migrated to alternate services that can be used safely and freely within their respective terms and conditions.