Freshpaint offers a HIPAA-compliant, Customizable, Zoomable, Panable map and location services APIs that can be embedded within healthcare focussed websites.
This version of Maps has been deprecated. If you're a new adopter of maps, please refer to Maps instead for instructions on how to integrate with the most up to date version of Maps. If you have already integrated and are looking for references, please read on.
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.
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:
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.
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.
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.
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.
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.
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.
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.
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.
// 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");
// 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);
});
// 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`
// 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"]}'
# 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'
# 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}'
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
