Maps SDK for Web

Class Copyright

The copyright service implementation provides a full copyrights notice in an HTML format that can be displayed to the user when the copyrights link is clicked.

The copyrights API can take as argument area which the copyrights concerns. If this argument is omitted the whole world is considered.

The API handles the "edge of the world" issue. Allowing to properly handle bounding box that is outside of world extends (-180, -90, 180, 90).

Parameters can be passed to the constructor or provided via convenient methods that can be chained until the method go performs the actual call.

The call is asynchronous therefore the user have two options for receive the response:

  • Passing a callback function.
  • Use the Promise returned by the go method to handle the response.

Constructor

Methods

boundingBox([newValue]): Object | Number[] | Object[] | String Chainable

Sets or returns the value of the boundingBox option. The bounding box is an area within the search results needs to limit to. If it is omitted then the whole world will be taken into consideration. In case the area specified exceeds the world boundaries the following actions will be taken depending of which side was exceeded: - Latitudes: the exceeded values will be replaced with their maximun. - Longitudes: The service will split the area into two (or more) valid bounding boxes and will execute a search request for each one and them merge the responses into a single result. This method is able to convert a number of popular formats into the bounding box. The supported formats are listed below: - {minLon: 0, minLat: 0, maxLon: 1, maxLat: 1} Plain object with the keys minLon, minLat, maxLon, maxLat. - L.LatLngBounds Leaflet's L.LatLngBounds object. - [0, 0, 1, 1] An array of numbers describing the bounding box following the order: minLon, minLat, maxLon, maxLat. - ol.Extent Open Layers extent object. - [ol.Coordinate, ol.Coordinate] An array of two open layers coordinate objects with the order: southWest, northEast. - [[0, 0], [1, 1]] A two-dimensional array with two indexes [southWest, northEast], each one with latitude and longitude values. - "0,0,1,1" Comma separated string with numbers in the order: minLon, minLat, maxLon, maxLat. - [{lon: 0, lat: 0},{lon: 1, lat: 1}] A one-dimensional array with two objects in the order: southWest, northEast and each object with a lat and lon keys. - [{lng: 0, lat: 0},{lng: 1, lat: 1}] A one-dimensional array with two objects in the order: southWest, northEast and each object with a lat and lon keys. - [L.LatLng, L.LatLng] A one-dimensional array with two L.LatLng instances in the order: southWest and northEast. - google.maps.LatLngBounds Google Maps bounds object. - google.maps.LatLngBoundsLiteral Google Maps bounds object. - [LatLng, LatLng] array of two google.maps.LatLng. - [LatLngLiteral, LatLngLiteral] array of two google.maps.LatLngLiteral.

Parameters
Name Description Required Type/Values Default
newValue Bounding box area in one of the supported formats No Object | Number[] | Object[] | String None
Throws

If the given argument cannot be converted into a valid value

Returns

The same service instance or the current option value if no argument was given

callback([newValue]): Function Chainable

Sets or gets the value of the option callback. This callback function will be called only after the go method successfully complete its task. Its first and unique argument passed to the callback will be the result of the request.

Parameters
Name Description Required Type/Values Default
newValue The new callback function No Function None
Throws

If the given argument is not a function

Returns

The same service instance or the current callback function if no argument was given

Example
function callbackFn(results) {
  console.log(results);
}
tomtom.fuzzySearch()
  .query("pizza")
  .callback(callbackFn)
  .go();

fail([newValue]): Function Chainable

Sets or gets the value of the option fail. This function is called when an error occurs (e.g. invalid values or a communication error). The callback will receive just one argument which is the error description. This parameter will be ignored if the callback function is not defined and therefore the go method will return a Promise that will be rejected if an error occurs. If you don't specificy a failure callback, the default behavior in case of encounter a problem is to throw an error.

Parameters
Name Description Required Type/Values Default
newValue The new callback function No Function None
Throws

If the given argument is not a function

Returns

The same service instance or the current callback function if no argument was given

Example
function successCallback(results) {
  console.log(results);
}
function failureCallback(error) {
  console.log(error);
}
tomtom.fuzzySearch()
  .query("pizza")
  .callback(successCallback)
  .fail(failureCallback)
  .go();

go([success], [fail]): Promise | Null

Perform the actual call to the web service.

It receives two optional arguments. The first one is a callback function that will be used when a successful response if received by the web service. The second one is another callback function that will be used only in case of failure.

Both arguments are shortcuts for the callback and fail methods respectively.

The final response from the service is an HTML string with the copyright information that have to be displayed. The whole respose is wrapped into a div element with the id copyrightMessage. Country names are enclosed within h4 elements and the copyrights information per each supplier is enclose in p elements. This makes styling with CSS fairly easy. An example response may look like this:

<div id="copyrightMessage"><h4>General Copyrights:</h4>
  <p>© 1992 – 2016 TomTom. All rights reserved. This
  material is proprietary and the subject of
  copyright protection, database right protection
  and other intellectual property rights owned
  by TomTom or its suppliers. The use of
  this material is subject to the terms of a license
  agreement. Any unauthorized copying or disclosure
  of this material will lead to criminal and civil
  liabilities.</p>
  <p>Data Source © 2016 TomTom</p>
</div>

The SDK provides a Promise polyfill for browsers (IE<9) without native ECMAScript 6 support.

Parameters
Name Description Required Type/Values Default
success The callback function to be called on case of success. No Function None
fail The callback function to be called on case of failure. If a success callback is not given this argument will be ignored. In that case the returned Promise should be used to handle the failures. No Function None
Returns

If the success callback is omitted (and wasn't defined one yet) this function will return a Promise

key([newValue]): String Chainable

Sets or returns the API key to be used in calls made by this service instance. Setting a key for each instance of this class is not needed if the key was already setted globally using the tomtom.searchKey() function. A valid API key is required to make use of the Search API services. It can be issued from TomTom's Developer Portal.

Parameters
Name Description Required Type/Values Default
newValue key API Key valid for requested service No String None
Throws

If the given argument cannot be converted to a valid value

Returns

The same service instance or the current option value if no argument was given

protocol([newValue]): String Chainable

Sets or returns the protocol option value to be used in the calls. Represents the type of protocol used to perform service call.

Parameters
Name Description Required Type/Values Default
newValue Protocol type No "http" | "https" None
Throws

If the given argument cannot be converted to a valid value

Returns

The same service instance or the current option value if no argument was given

updateMaxZoom(map, source)

Updates the max zoom property based on given source name. This method takes into account max zoom given in map.options property.

Parameters
Name Description Required Type/Values Default
map Map instance Yes Map None
source one of 'vector' or 'raster' Yes String None