Proximitii Documentation Last updated: 2022-08-15

This document goes through the basic required steps to start using and customizing all of the SDKs and APIs on the Proximitii platform.

Introduction

The following products from Proximitii were designed to be easy to use and fully customizable. Before you begin, make sure that you have obtained your public or private key(s) as they are required to authenticate any of the products listed in this document.

Products

Here are the current products offered by Proximitii:

Authentication

In order to use any of the Proximitii products, you will need a key. The keys will authenticate your access to the widgets or API. We have two different types of authentication, depending on which product is being called.

Public Key (Widget):

When using a widget, you’ll be asked for the URL of the website you want to put it on, and given a public key in return. Use this public key in your widget, and as long as it’s installed on the correct site, the key will work.

Private Key (API):

When using the API, a public key and a private key is required to authenticate the API. Send these together in your API calls. Do not expose the private key in code or on publicly viewable endpoints.

If you do not have a key, please contact info@proximitii.com.

Service Areas

These are the areas that we currently cover:

USA All 50 states and D.C.
Canada Full Coverage of all Provinces and Territories.

Local Lifestyle Widget

The Local Lifestyle Widget provides detailed information and scores on nearby points of interest from up to 12 categories.

Local Lifestyle Widget

Installation

Add the following embed code to your page or template. In order for the widget to render, you must add your own public key and you must pass the latitude and longitude.


 <script src="https://widget-api.proximitii.com/proximitii-embed.js"></script>
<div id="prox-map"></div>
<script type="module">
window.onProximitiiLoad = () => {
let proximitiiMap = new Proximitii('prox-map')

//Make sure to put in your own public key!
proximitiiMap.setPublicKey("YOUR OWN KEY HERE")

proximitiiMap.setCenter(43.65925118924679, -79.34521876247898)

proximitiiMap.setOptions({
    primaryColor: '#02A0E9',  
    hideScores: false, 
    hideTitle: false, 
    hideRadius: false, 
    hideBackgroundImage: false, 
    markerIconColor: 'white',
    height: '500px',
    customOrderCategories: false,
    disableGestureHandling: false
})

proximitiiMap.setColors({
    scoreCircle: "#189CAD",
    locationMarker: "#537BBE",
})

proximitiiMap.render()
}
</script>


How to Install the Widget:


First, start by importing the Proximitii script.

 <script src="https://widget-api.proximitii.com/proximitii-embed.js"></script>

And a div for the map to fill.

 <div id="prox-map"></div>

Next, you can access the onProximitiiLoad function and pass in a callback, where you create a new instance of Proximitii.

 <div id="prox-map"></div>
<script type="module">
window.onProximitiiLoad = () => {
    let proximitiiMap = new Proximitii('prox-map')

    //Make sure to put in your own public key!
    proximitiiMap.setPublicKey('KEY')

    proximitiiMap.setCenter(44.656834, -63.5982224)

    proximitiiMap.render()
}
</script>

You can also set and reset options, including the center, at any time, if you call render after. Various colors may also be changed.

 proximitiiMap.setOptions({
        primaryColor: '#02a0e9', 
        title: 'Proximitii Score',
        hideScores: false, 
        hideTitle: false, 
        hideRadius: false, 
        hideBackgroundImage: false, 
        markerIconColor: 'white',
        height: '500px',
        sortCategoriesScore: false,
        gestureHandling: false
    })
    
proximitiiMap.setColors({
        scoreCircle: "#189CAD",
        locationMarker: "#537BBE",
        link: "#02a0e9",
        categoryScore: "primary",
        categoryScoreText: "#ffffff"
    })

Always be sure to call render AFTER setting or resetting any options.

Customization

There are many customization options. See below for how to customize the widget.


General Options:

Parameter Name Description Default Value Accepted Values Field Name / Function
Latitude Sets the latitude of center N/A Decimal between -90 and 90 setCenter(latitude, longitude)
Longitude Sets the longitude of center N/A Decimal between -180 and 180 setCenter(latitude, longitude)
Custom Title Sets the title text Proximitii Score Any valid text setOptions({title})
Title Size Sets the CSS size for the title 24px Any valid CSS value setOptions({titleSize})
Height Sets the height for desktop 500px Any valid CSS value (min. height is 450px) setOptions({height})


Display Options:

Parameter Name Description Default Value Accepted Values Field Name / Function
Hide Scores Hides the score circles for each category false true/false setOptions({hideScores})
Hide Title Hides the top text & the overall score false true/false setOptions({hideTitle})
Hide Radius Hides all the radius options false true/false setOptions({hideRadius})
Hide Background Hides the background image in the header false true/false setOptions({hideBackground})
Categories Specifies which categories to display N/A true/false setOptions({categories})
Custom Order Categories Orders categories based on input order false true/false setOptions({customCategoryOrder})
Disable Gesture Handling Enables scroll wheel zoom and map interaction false true/false setOptions({disableGestureHandling})


Color Options:

Parameter Name Description Default Value Accepted Values Field Name / Function
Primary Color Sets the color of the score circle, category name hover and POI pins on the map. N/A hex color setOptions({primaryColor})
Score Circle Sets the color of the circle around the overall score #189CAD hex color setColors({scoreCircle})
Location Marker Sets the color of the POI pins on the map #537BBE hex color setColors({locationMarker})
Marker Icon Color Sets the icon color of pins white "white" or "black" setOptions({markericonColor})
Category Score Sets the color of the category circle default null or hex color setColors({categoryScore})
Links Sets the color of the category name hover #02A0E9 hex color setColors({link})
Category Score Text Sets the color of the score inside the category circle #FFFFFF hex color setColors({categoryScoreText})


Tech Options:

Parameter Name Description Field Name / Function
Public Key The public key provided to you setPublicKey(key)
Extreme Defer If page speeds are a concern, you can select this option, which will defer loading of the widget on your page until the first user interaction. This almost completely bypasses any page speed testers. To manually use this option, link to ‘https://widget-api.proximitii.com/proximitii-embed-defer.js’ instead of ‘https://widget-api.proximitii.com/proximitii-embed.js’
Version The version of the widget to load. Unless you have a very specialized implementation which requires a specific build, it’s recommended to stick with “latest”, which will auto update which version of the widget loads as new versions come out. To manually use this option, you can append the embed link with the version number, i.e. “https://widget-api.proximitii.com/1.1.1/proximitii-embed.js”

Categories

These are the categories that are available in the Local Lifestyle Widget.

# Category Name Value
1 Child Care childcare
2 Coffee Shops coffee
3 Elementary Schools elementaryschools
4 Entertainment entertainment
5 Fitness fitness
6 Food & Drink food
7 Groceries grocery
8 Health & Safety health
9 High Schools highschools
10 Parks parks
11 Shops shop
12 Transit transit

WordPress

To install the Local Lifestyle Widget on WordPress, please see the instructions below.

Install:
  1. Download the plugin from here, it’s a zip file
  2. Navigate to your WordPress dashboard, and go to “Plugins”
  3. Click “Add New”
  4. On the next page click “Upload Plugin” > “Choose File”
  5. Navigate to your downloads, and upload the package
  6. Click “Install”
  7. Go back to your list of Plugins, and find the Proximitii Widget plugin- click the “Activate” button underneath
  8. You should now see “Proximitii Widget” on your sidebar- click on that.
  9. Fill out settings. These are your default settings for your whole website- anytime you update here, it will update all widgets on your site automatically.

Shortcodes:
  1. You can use the widget anywhere on your WordPress site you can use shortcodes - [proximitii]
  2. The bare minimum you’ll need to pass in the latitude and longitude as parameters, like this - [proximitii latitude=”xx” longitude=”yy”]
  3. You can also override any settings you set on the settings page in each shortcode - [proximitii latitude=”xx” longitude=”yy” titleSize=”32px”]
  4. You can use The Playground page to generate shortcodes

API

The Proximitii API (Application Programming Interface), allows you to connect directly to our servers to download data.

Example Call

					https://widget-api.proximitii.com/api/map/locations?lat=43.659251&long=-79.345218&dataType=all&radius=6400&limit=2&categories=coffee,park,elementaryschools&public_key={public_key}&private_key={private_key}

Keys

In order to call the API successfully, you will need a public and private key. Make sure to store the keys safely and do the API call on backend so the keys are not exposed to the public.

Values

Parameter Name Description Default Value Accepted Values Field Name
Latitude Sets the latitude of center N/A Decimal between -90 and 90 setCenter(latitude, longitude)
Longitude Sets the longitude of center N/A Decimal between -180 and 180 setCenter(latitude, longitude)
Data Type Type of data to return all all, scores, locations, overall_score dataType
Radius Sets maximum search radius (meters) 6400 1 - 20000 radius
Limit Sets the maximum number of results 12 1 - 25 limit
Categories Selects specific categories only N/A comma delimited (see table below) categories
Public Key Your public key N/A N/A public_key
Private Key Your private key N/A N/A private_key


Categories:

Category Name Value
Child Care childcare
Coffee Shops coffee
Elementary Schools elementaryschools
Entertainment entertainment
Fitness fitness
Food & Drink food
Groceries grocery
Health & Safety health
High Schools highschools
Parks parks
Shops shop
Transit transit

Sample Output

 {
  "OverallScore": 90,
  "Active": 1,
  "Data": {
    "coffee": {
      "Category": "coffee",
      "Score": 9,
      "Locations": [
        {
          "AmenityID": 30342,
          "Country": "CA",
          "Name": "Starbucks",
          "Address": " ",
          "Category": "coffee",
          "Tag": "Coffee Shop",
          "Coord": {
            "Lat": 43.6603708,
            "Long": -79.3425969
          },
          "WalkingTime": 4
        },
        {
          "AmenityID": 14544,
          "Country": "CA",
          "Name": "Purple Penguin Cafe",
          "Address": "889 Queen Street East",
          "Category": "coffee",
          "Tag": "Coffee Shop",
          "Coord": {
            "Lat": 43.6604252,
            "Long": -79.3422613
          },
          "WalkingTime": 4
        }
      ],
      "Count": 2
    },
    "park": {
      "Category": "park",
      "Score": 9,
      "Locations": [
        {
          "AmenityID": 921809,
          "Country": "CA",
          "Name": "McCleary Playground",
          "Address": "80 McGee Street",
          "Category": "park",
          "Tag": "Park",
          "Coord": {
            "Lat": 43.6593088127695,
            "Long": -79.3454086596916
          },
          "WalkingTime": 1
        },
        {
          "AmenityID": 931509,
          "Country": "CA",
          "Name": "Saulter Street Parkette",
          "Address": "25 Saulter Street",
          "Category": "park",
          "Tag": "Park",
          "Coord": {
            "Lat": 43.6577088206208,
            "Long": -79.3465032129895
          },
          "WalkingTime": 3
        }
      ],
      "Count": 2
    },
    "elementaryschools": {
      "Category": "elementaryschools",
      "Score": 9,
      "Locations": [
        {
          "SchoolID": 13009,
          "NCESSchoolID": "153214",
          "Address": "935 Dundas St E",
          "City": "Toronto",
          "StateAbbr": "ON",
          "Postal": "M4M 1R4",
          "Phone": "416-393-9565",
          "Site": "http://schoolweb.tdsb.on.ca/dundas",
          "LowGrade": "JK",
          "HighGrade": "5",
          "IsPre": 0,
          "IsElem": 1,
          "IsMid": 0,
          "IsHigh": 0,
          "Type": "Elementary",
          "Students": "465",
          "Coord": {
            "Lat": 43.6620635986328,
            "Long": -79.3486251831055
          },
          "ProfMath": "67",
          "ProfLang": "82",
          "SchoolScore": 74.5,
          "WalkingTime": 7,
          "Name": "Dundas Junior Public School"
        },
        {
          "SchoolID": 13106,
          "NCESSchoolID": "374733",
          "Address": "180 Carlaw Ave",
          "City": "Toronto",
          "StateAbbr": "ON",
          "Postal": "M4M 2R9",
          "Phone": "416-393-9494",
          "Site": "http://schoolweb.tdsb.on.ca/morsestreet",
          "LowGrade": "JK",
          "HighGrade": "6",
          "IsPre": 0,
          "IsElem": 1,
          "IsMid": 0,
          "IsHigh": 0,
          "Type": "Elementary",
          "Students": "510",
          "Coord": {
            "Lat": 43.6601181030273,
            "Long": -79.3401336669922
          },
          "ProfMath": "57",
          "ProfLang": "86",
          "SchoolScore": 71.5,
          "WalkingTime": 7,
          "Name": "Morse Street Junior Public School"
        },
      ],
      "Count": 2
    }
  }
}

Proximitii Maps

Documentation coming soon.

Proximitii Maps

Section Item 4.1

Section Item 4.2

Section Item 4.3

FAQs

FAQ's coming soon.

Section Item 9.1 (FAQ Category One)

Section Item 9.2 (FAQ Category Two)

Section Item 9.3 (FAQ Category Three)