BestParking widget

Embed a parking finder in your website or application

About

BestParking's widget enables you to embed parking search functionality into any website or application.

Usage

To use BestParking widget one should:

  1. include jQuery library (any recent version), for example, like this:
    <script type="text/javascript" src="https://code.jquery.com/jquery-1.11.3.min.js"></script>
    
  2. include BestParking script:
    <script type="text/javascript" src="//widget.bestparking.com/loader.js"></script>
                    
  3. initialise BestParking widget:
    <div id="parkingLocator"/>
    <script>
      $(function() {
        $('#parkingLocator').findBestParkingBlock({
          lat: 40.767098,
          lng: -73.977264,
          default_zoom:  16,
          min_zoom: 11,
          max_zoom: 18
        });
      });
    </script>
    
    See documentation for full list of available options.

loader.js is a tiny library that will load all resources that are required for the widget to work. It has a few options that control widget's version and the way the widget is embedded into the page.

Current stable version is 1.1.28, unstable version is 1.1.29.

Security

The widget is available both via HTTP and HTTPS; by default, it will use the same protocol as the page that it is embedded into. You can override that by explicitly specifying the protocol in the loader URL, e.g., use https://widget.bestparking.com/loader.js to always load the widget via HTTPS.

All communications with the reservations and payments backends ALWAYS use HTTPS regardless of the protocol used to load the widget itself.

However, currently there's one minor caveat with widget over HTTPS: it will load facility images over HTTP in all cities except New York (in New York images will be loaded over HTTPS, so there's nothing to worry about). That is not a major security issue. Moreover, this situation is temporary. Nevertheless, this will cause browsers of your users do 2 things: 1) print notifications to the console - one for each facility popup user opens 2) change green "secured" icon to the left of browser's URL panel to yellow when user opens a facility popup. The reason for this behaviour is that your page (loaded over HTTPS) turns out to refer to resources that are loaded via HTTP; modern browsers consider this situation as a potential risk.

Documentation

BestParking widget is currently available as jQuery plugin. That means that jQuery must be loaded prior to widget's library. jQuery version does not matter in case when widget is loaded into an iframe (see loader options below). To embed widget into a page jQuery version must be >= 1.10.

Loader options

Loader options should be specified directly in the script URL. For example,

<script type="text/javascript" src="//widget.bestparking.com/loader.js?v=1&t=embed"></script>
              

Currently, there are 2 options:

  • v - widget version to load. If this option is omitted, latest stable version is loaded. We are using semver versioning. You can specify only major version (v=1, load latest version from 1 branch), major and minor versions (v=1.1, load latest version from 1.1 branch) or exact version (v=1.1.29). Besides this, you can use stable and latest keywords, that will refer to latest stable or latest unstable version, respectively.
  • t - how to embed widget into a page. Currently there are two ways: iframe (the default) and embed.

    The former injects an iframe into a page. All the resources that are needed for the widget to work are loaded inside this iframe. This won't cause any library conflict. The downside is that some libraries (e.g., jQuery) will be loaded twice, hence, widget's load time (and load time of your page) will be relatively higher.

    The latter (embed) injects BestParking script and Google Maps, if they aren't loaded already, directly into the page. This is an experimental feature for now! On one hand, it allows to reduce the overall download size if you have some third-party library, e.g., Twitter Bootstrap or Google Maps, already included on the page. On the other hand, it may introduce version clashes, if your page uses other (especially, lower) versions of the libraries needed by the widget.

If no loader options are specified, the widget defaults to latest stable version, loaded in an iframe.

findBestParkingBlock jQuery plugin options

Widget accepts a number of options that can be passed to plugin.

NameExampleDescription
width width: 1000

Widget's width in pixels. Integer. Optional. Defaults to 100%.

If omitted, defaults to container's width and adapts widget's width if window dimensions are changed. Has no effect on mobile platforms with small screens.

Minimal allowed width is 450px.

It is recommended to set both width and height to some explicit values that are not less than minimal allowed values.

height height: 600

Widget's height in pixels. Integer. Optional. Defaults to 100%.

If omitted, defaults to container's height and adapts widget's height if window dimensions are changed. Has no effect on mobile platforms with small screens. The default height is 100%, which is calculated relatively to the parent container, so if you would like the widget to occupy an exact height, you should specify the container's height.

Minimal allowed height is 550px.

It is recommended to set both width and height to some explicit values that are not less than minimal allowed values.

city_or_airport

city_or_airport: 'Washington, DC'

city_or_airport: 'New York'

City or airport name. String. Optional. No default value.

Limit showed garages to specified location.

arrival arrival: '2015-09-01 15:12'

Date and time of arrival. Formatted string. Optional. No default value.

Set the default arrival date and time. Useful for showing parkings for particular location and time, e.g. some event.

departure departure: '2015-09-11 11:10'

Date and time of departure. Formatted string. Optional. No default value.

Set the default departure date and time. Useful for showing parkings for particular location and time, e.g. some event.

fixed_arrival_time fixed_arrival_time: '15:00'

Fix arrival time to some predefined value or range. Formatted string. Optional. No default value.

Either set arrival time (only time, not date) to some fixed value or allow arrival time to change in some predefined range. Time is specified in 24H format. Range is two times separated by dash. For example, the following values are valid: '13:00', '03:25', '08:10-16:40'.

This option affects only time; the date can be freely changed. If time is fixed to a certain value, it can't be changed at all. In case of time range it can be changed inside this time range only.

fixed_departure_time fixed_departure_time: '18:00-21:30'

Fix departure time to some predefined value or range. Formatted string. Optional. No default value.

Everything that is said about fixed_arrival_time property above applies to this property also.

When both fixed_arrival_time and fixed_departure_time are set and departure time is earlier than arrival time (or departure time range starts earlier than arrival time range), then departure date is shifted by one day to the future.

union_only union_only: false

Special argument for filtering garages by belonging to some union. Boolean. Optional. Defaults to false.

Probably, this argument should not be used without our consultation.

company

company: 'QUIK PARK'

company: 'Colonial'

company: 'IPARK'

Show only garages belonging to the specified company. String. Optional. No default value.

Probably, should be used only by parking companies on their websites.

address address: 'Pell St, New York, US'

Geocode this address using Google Maps geocoder and center map at the first result from the response. String. Optional. Works only if lat and lng are not set.

Important! Google's geocoder is called prior to loading the widget, thus, the widget's loading is delayed by the time needed for geocoder to respond. Therefore, for any static location it's worth to set lat and lng instead.

lat lat: 38.908712

Center map at this latitude. Float. Optional. Defaults to New York center latitude (40.7127837)

lng lng: -77.023405

Center map at this longitude. Float. Optional. Defaults to New York center longitude (-74.0059413)

default_zoom default_zoom: 16

Map default zoom level. Optional. Defaults to 15

daily_monthly_enable daily_monthly_enable: false

Enable monthly parking. Boolean. Optional. Defaults to false.

Enable daily/monthly parking switch in the control panel and all related montly parkings functionality.

garage_street_enable garage_street_enable: false

Enable street parking. Boolean. Optional. Defaults to false.

This option is reserved for the future and currently has no effect.

hint1 hint1: 'Cambria Suites'

Show hint (red star icon with tooltip) at latitude and longitude specified by lat and lng options. Tooltip text is defined by this option. String. Optional. No default value.

min_zoom min_zoom: 11

Set the minimal allowed zoom level. Integer. Optional. Defaults to 11.

max_zoom max_zoom: 18

Set the maximal allowed zoom level. Integer. Optional. Defaults to 18.

locations locations: '437,678'

Limit showed garages to by their IDs. Comma-separated string. Optional. No default value.

This option allows to specify list of garages that should be shown on the map.

clustering clustering: true

Group garages into clusters on low zoom levels. Boolean. Optional. Defaults to true.

Clustering begins at zoom level 15 for garages belonging to cities and neighbourhoods and at zoom levl 11 for airport garages.

manageHistory manageHistory: true

Update browser's location and history on every user action. Boolean. Optional. Defaults to false.

Experimental option! Use with caution. Allows each garage, city and search results to have it's own unique URL.

filterCountries filterCountries: true

When user types in a location name to search for, limit Google Autocomplete results to US and Canada. Boolean. Optional. Defaults to true.

If this option is false, Google Autocomplete's results for the whole world are shown.

This option will be forced to false on Safari running on iOS, unless filterCountriesOniOS is true. See below for more info.

filterCountriesOniOS filterCountriesOniOS: true

Limit Google Autocomplete's output to US and Canada on Safari on iOS devices. Boolean. Optional. Defaults to false.

There's a known bug of Twitter Typeahead library that causes application freeze when used on iOS. By default, the widget detects Safari on iOS and disables filterCountries option so that Twitter Typeahead library is not used. Set filterCountriesOniOS to true to overcome this. Be warned that this may cause browser freeze.

animateMap animateMap: true

Animate garage popup when user switches from one garage to another without closing existing popup. Boolean. Optional. Defaults to true.

Embeddable button

BestParking widget can be embedded into a website as a button using the following code:

<a href="http://widget.bestparking.com/lib/stable/loader.iframe.html?hint1=ABC+Business&address=Pell+St+New+York+US&default_zoom=16" target="_blank">
  <img src="http://widget.bestparking.com/lib/stable/img/button-medium.png">
</a>

The code above will result in the following button:

All options that are listed above in documentation section can be specified as URL parameters for the link. Please, use standard URL encoding for special characters; for example, please note the encoding of spaces in the example above.

The button image is available in four sizes:

File name Size, px Image
button-big.png 300x60
button-medium.png 200x40
button-small.png 150x30
button-xsmall.png 100x20

Examples

BestParking widget is used by a number of US parking operators:

Please, see these web pages and their source code for examples.

Migration from the old widget

There's an early modification of this widget (version 0.99) accessible at //www.bestparking.com/js/bp_widget_lightbox.js. If you used our widget before, then you are probably on this version right now. This URL exists for historical reasons and code located there will not be maintained and updated; moreover, it can be removed some day in the future. We encourage all our users to migrate to new URL //widget.bestparking.com/loader.js.

The migration is simple: you only need to change the URL you use to load the widget to //widget.bestparking.com/loader.js. Nevertheless, issues can appear as the new widget is not exactly the same code. Taking that into account, we suggest to test the widget on some new page on your website first. In most cases, everything will work out of the box.

You have the option to stay at the old version 0.99 of the widget (which is exactly what you are using right now). To do that, please use the following URL: //widget.bestparking.com/lib/0.99/loader.js. This is not recommended, do it only if you have to; for example, if your page breaks and you have no time to fix it right now. Please, consider using newer version at your earliest convenience.

In case of any questions regarding migration to the new version of the widget, please, write us at vladimir at bestparking.com.

Major changes since version 0.99

  • airport reservations
  • monthly parkings
  • support for arbitrary arrival date in the future (no 1-month limit)
  • improved appearance
  • correct behaviour in responsive environment
  • a lot of bug fixes and minor improvements
  • better mobile experience
  • smaller size
  • support for direct embedding of the widget into a webpage (experimental)