Maps

Freshpaint offers a HIPAA-compliant, Customizable, Zoomable, Panable map and location services APIs that can be embedded within healthcare focussed websites.

Introduction

Many healthcare organizations utilize maps as part of their web presence to aid in user conversions by understanding where a healthcare provider is located. Freshpaint offers a series of HIPAA safe base components for building Maps components and location services into a web page.

Map Tiles

Map tiles are the data about how to draw a map at a particular location. These tiles contain all the information about the locations of everything to be drawn a map, all the rivers, roadways, labels, buildings, and more.

Freshpaint serves tile information based on Open Street Map, the largest open dataset of every location on planet earth, supported by a large community and open to contributions.

Drawing a Map

Freshpaint recommends using MapLibre GL JS as the code library to use to draw the maps on a web page. Maplibre-js is a fully featured open-source library that understands the map tiles served by Freshpaint and can render them into a map on a web page. Maplibre also provides similar functionality as other mapping services you may have used or seen elsewhere.

If your website is built using a framework, you can use any of the MapLibre libraries or wrappers that are available for the particular framework.

Freshpaint provides access to the unmodified MapLibre libraries from the freshpaint-hipaa-maps.com domain if you want a convenient place to access the web libraries for drawing a map.

<link href="https://freshpaint-hipaa-maps.com/maplibre-gl@3.x/dist/maplibre-gl.css" rel="stylesheet" type="text/css">
<script src="https://freshpaint-hipaa-maps.com/maplibre-gl@3.x/dist/maplibre-gl.js" type="text/javascript"> </script>

Location Services API

Some more interactive web experiences require the use of location services APIs. Freshpaint provides access to a number of location services APIs that are used for Geocoding, Reverse Geocoding, and location search.

For example, a website developer may want to organize location results by distance from a website visitor. This might be done through requesting a zip code from the user. The location API allows the website to request the coordinates of a zip code, and then knowing the latitude and longitude of both the zip code and locations allows code to be written that will reorganize the results based on distance.

Freshpaint provides access to the Amazon AWS Location Service for providing location APIs to a website visitor.

Using the Location Services API

Freshpaint provides access to the Amazon AWS Location Services by accessing Freshpaint services.

So in the amazon location services docs, you might see:

/places/v0/indexes/IndexName/search/suggestions?key=Key

You would instead use

https://freshpaint-hipaa-maps.com/places/v0/indexes/freshpaint/search/suggestions?token=YOUR-ENVIRONMENT-ID-HERE

See https://documentation.freshpaint.io/reference/faqs/where-do-i-find-my-environment-id on how to find you're environment ID and replace YOUR-ENVIRONMENT-ID-HERE with the token for you're particular Freshpaint environment.

The AWS API Docs indicate the use of an API Key as the ?key=Key parameter on their examples. When using the location services with Freshpaint you instead use ?token=YOUR-ENVIRONMENT-ID-HERE to access the location services from Freshpaint. The key parameter is not used when accessing the location services through freshpaint-hipaa-maps.com

Common Functions

SearchPlaceIndexForSuggestions

Generates suggestion results for addresses or point of interest based on partial or misspelled free-form text. This could be used for functionality related to autocomplete, autosuggest, or fuzzy matching.

AWS Docs for SearchPlaceIndexForSuggestions

SearchPlaceIndexForText

Geocodes free-form text, such as an address, name, city, or region to allow you to search for a place or point of interest. You can apply filters or bounding boxes in the request to only return locations in the correct geography.

AWS Docs for SearchPlaceIndexForText

SearchPlaceIndexForPosition

Sometimes referred to as Reverse Geo-coding, takes a given coordinate and returns a Place and information such as address, country, etc related to the returned Place.

AWS Docs For SearchPlaceIndexForPosition

GetPlace

Returns additional information about a place. Other API operations may return a PlaceID, and GetPlace can be used to find the address, categories, countries and more about the PlaceID.

AWS Docs for GetPlace

Examples

The example site has a full working demo that you can inspect and customize to your needs.

Freshpaint Maps Integration Demo

A demo site showing the Freshpaint map connected to clickable location cards. When you click on a location card, the map automatically focuses on the location. When you click on a pin, the location cards automatically scroll to the selected location.

You can use view-source in your browser to see how the demo was built in pure Javascript and HTML.

Map Setup: Vanilla JS

Freshpaint uses MapLibre as an open-source renderer to display the map. You will need to load MapLibre and its stylesheet.

<link href="https://freshpaint-hipaa-maps.com/maplibre-gl@3.x/dist/maplibre-gl.css" rel="stylesheet" type="text/css">
<script src="https://freshpaint-hipaa-maps.com/maplibre-gl@3.x/dist/maplibre-gl.js" type="text/javascript"> </script>

Creating a Map

// Styles affect how the maps look:
// We currently support the following styles:
//   "standard-light":      colorized, typical map style
//   "standard-dark":       colorized, typical dark map style
//   "visualization-light": grayscale, elegant black and white style
//   "visualization-dark":  grayscale, elegant dark black and white style
const style = "standard-light" 

// Replace the environment ID below with your freshpaint environment ID
// Go to the URL below to see how to find your Freshpaint Environment ID
// https://documentation.freshpaint.io/reference/faqs/where-do-i-find-my-environment-id
const envId = "YOUR-FRESHPAINT-ENVIRONMENT-ID"

const map = new maplibregl.Map({
  container: "map",
  style: `https://freshpaint-hipaa-maps.com/${envId}/${style}/style-descriptor`,

  // longitude and latitude of the map's origin
  // Note: this is backwards compared to google maps
  center: [-87.6800, 41.8500],

  // Zoom levels (rough descriptions):
  // 15 : a close street view
  // 13 : city neighborhoods
  // 11 : entire region (Chicagoland)
  zoom: 13,
});

// This adds a toolbar for zooming an panning:
// + : zoom in
// - : zoom out
// compass for rotating (e.g. north facing up or south facing up)
map.addControl(new maplibregl.NavigationControl(), "top-left");

Adding pins with popups

// Note: LngLat is reversed from google maps which does LatLng.
const markers = [
  {
    "LngLat": [-87.7276, 41.7919],
    "Header": "UI Health",
    "Href": "https://hospital.uillinois.edu/"
  },
  {
    "LngLat": [-87.69738, 41.85505],
    "Header": "Saint Anthony Hospital",
    "Href": "https://sahchicago.org/"
  }
];

// You can customize popups with arbitrary HTML
// Here, we just do a simple header and link to the website
const newPopup = (m) => new maplibregl.Popup({ offset: 25 })
                                      .setHTML(`<div>
                                                    <h3>${m.Header}<\/h3>
                                                    <a href="${m.Href}">${m.Href}<\/a>
                                                <\/div>`)

markers.forEach((m) => {
  const popup = newPopup(m);
  const marker = new maplibregl.Marker({color: "#808080"})
                               .setLngLat(m.LngLat)
                               .setPopup(popup)
                               .addTo(map);
});

Full working example

See the working demo at https://freshpaint-hipaa-maps.com/demo/index.html for a demo with the Freshpaint map connected to clickable location cards.

This demo shows how to add on-click handlers to customize behaviors when users click on Map pins. It also shows how to link external actions to the Map (e.g. so on-click outside of the map cause the map to recenter).

Location Search Setup:

Freshpaint also offers a HIPAA-compliant Location search service that finds location matches to user inputs. We offer a backend that can be used with your autocomplete frontend of choice.

Example location autocomplete.

API Details

The API is accessible at

// Replace the environment ID below with your freshpaint environment ID
// Go to the URL below to see how to find your Freshpaint Environment ID
// https://documentation.freshpaint.io/reference/faqs/where-do-i-find-my-environment-id

POST `https://freshpaint-hipaa-maps.com/places/v0/indexes/freshpaint/search/suggestions?token=YOUR-ENVIRONMENT-ID-HERE`

Request body

Because we use AWS Location Services, a full account of all supported features, and inputs can be found here: https://docs.aws.amazon.com/location/latest/APIReference/API_SearchPlaceIndexForSuggestions.html

Sample CURL request

// Replace the TOKEN variable with your freshpaint environment ID
// Go to the URL below to see how to find your Freshpaint Environment ID
// https://documentation.freshpaint.io/reference/faqs/where-do-i-find-my-environment-id

TOKEN="YOUR-FRESHPAINT-ENV-ID-HERE"

curl -H 'Content-Type: application/json' \
"https://freshpaint-hipaa-maps.com/places/v0/indexes/freshpaint/search/suggestions?token=$TOKEN" \
-d '{"Text": "Good", "MaxResults": 8, "BiasPosition": [-87.69420, 41.86181], "FilterCountries": ["USA"], "FilterCategories": ["MunicipalityType"]}'

Reverse Geocoding Setup:

Freshpaint also offers a HIPAA-compliant Reverse Geocoding API that allows you to look up an address based on Latitude and Longitude.

API Details

The API is accessible at

# Replace the environment ID below with your freshpaint environment ID
# Go to the URL below to see how to find your Freshpaint Environment ID
# https://documentation.freshpaint.io/reference/faqs/where-do-i-find-my-environment-id

POST 'https://freshpaint-hipaa-maps.com/places/v0/indexes/freshpaint/search/position?token=YOUR-ENVIRONMENT-ID-HERE'

Request body

Because we use AWS Location Services, a full account of all supported features, and inputs can be found here:

SearchPlaceIndexForPosition - Amazon Location ServiceAmazon Location Service

Sample CURL request

# Replace the TOKEN variable with your freshpaint environment ID
# Go to the URL below to see how to find your Freshpaint Environment ID
# https://documentation.freshpaint.io/reference/faqs/where-do-i-find-my-environment-id
TOKEN="YOUR-FRESHPAINT-ENV-ID-HERE"

curl -H 'Content-Type: application/json' \
"https://freshpaint-hipaa-maps.com/places/v0/indexes/freshpaint/search/position?token=$TOKEN" \
-d '{"Position": [-122.3394,47.6159], "MaxResults": 8}'

Frequently Asked Questions

Can I use Freshpaint maps with React, Angular, or other web frameworks?

Yes. Freshpaint hasn't seen enough interest in any of these to prepare examples, but all that should be needed is to embed maplibre-js and point the library at the Freshpaint tiles as our regular JS demos use. If you need help you can always contact Freshpaint support.

Can I zoom the map to automatically capture all of my locations?

Yes. The maplibre fitBounds call supports providing a list of Longitude and Latitude pairs, and will provide a bounding box that contains all the added pins. When calling fitBounds on the map make sure to add some padding so any pins are not right on the edge of the bounding box.

bounds = new maplibregl.LngLatBounds();
bounds.extend(m.LngLat); // Add every LngLat to the bounds
map.fitBounds(bounds, { padding: 100 }); // Set the padding to how much extra space is needed

Can I use browser based location services to identify the location of the website visitor?

Many browser support a geolocation API which will give you approximate coordinates of the browser if allowed by the user. See the Geolocation API docs for what most web browsers will provide for accessing web visitor coordinates.

Can I install maplibre into my project instead of using the version from Freshpaint

Yes. The maplibre libraries provided by Freshpaint servers are not modified.