Maps

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

Welcome to the latest version of our Maps feature.

• New users: Please continue reading to learn more.

• Existing users of the older version seeking references: Please refer to Maps v0 (deprecated).

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 AWS's Location Services which uses HERE maps as its provider.

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:

/v2/autocomplete?key=Key

You would instead use

https://freshpaint-hipaa-maps.com/v2/autocomplete?token=YOUR-ENVIRONMENT-ID-HERE

See https://documentation.freshpaint.io/reference/faqs/where-do-i-find-my-environment-id on how to find your environment ID and replace YOUR-ENVIRONMENT-ID-HERE with the token for your 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

Please refer to the AWS Location Services Places documentation for details on how to use the following actions:

• Autocomplete: completes potential places and addresses as the user types, based on the partial input.

• Geocode: converts a textual address or place into geographic coordinates.

• GetPlace: finds a place by its unique ID. A PlaceId is returned by other listed actions.

• ReverseGeocode: converts geographic coordinates into a human-readable address or place.

• SearchNearby: queries for points of interest within a radius from a central coordinates, returning place results with optional filters such as categories, business chains, food types and more.

• SearchText: searches for geocode and place information. Can use the query ID from Suggest action to run a follow up query.

• Suggest: provides intelligent predictions or recommendations based on the user's input or context, such as relevant places, points of interest, query terms or search category.

Examples

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

Freshpaint Maps Integration Demofreshpaint-hipaa-maps.com

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/v2/autocomplete?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:

Autocomplete - 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 'https://freshpaint-hipaa-maps.com/v2/autocomplete?token=$TOKEN' \
  -H 'accept: application/json' \
  -d '{"QueryText":"chicago", "BiasPosition": [-87.69420, 41.86181], "MaxResults":8,"Filter":{"IncludeCountries":["USA"]}}'

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/v2/reverse-geocode?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:

ReverseGeocode - 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 'https://freshpaint-hipaa-maps.com/v2/reverse-geocode?token=$TOKEN' \
  -H 'accept: application/json' \
  -d '{"QueryPosition": [-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.

Does the Freshpaint SDK need to be installed on a page for the Maps feature to work?

No, the Maps feature can work independently on your page without depending on the presence of the Freshpaint SDK. You only need the Freshpaint SDK loaded if you wish to track interactions with the map. Otherwise, it can be used as a standalone HIPAA-compliant map plugin.