سیدار مپ API Documentation
< Back to Platforms

Cedarmaps Web SDK

CedarMaps JS is a javascript library for building interactive maps. It's simply a wrapper for Mapbox Javascript API, (The current version is v3.1.1) which is itself built as a Leaflet plugin. You can read about its launch.

Table of Contents

Basic Usage

Recommended usage is via the CedarMaps CDN. Just include CSS and JavaScript files in <head> section of your HTML file.

<script src='https://api.cedarmaps.com/cedarmaps.js/v1.8.0/cedarmaps.js'></script>
<link href='https://api.cedarmaps.com/cedarmaps.js/v1.8.0/cedarmaps.css' rel='stylesheet' />

and put the following code in the <body> of your HTML file:

<div id='map' style='width: 400px; height: 300px;'></div>

<script type="text/javascript">
    L.cedarmaps.accessToken = "YOUR_ACCESS_TOKEN"; // See the note below on how to get an access token

    // Getting maps info from a tileJSON source
    var tileJSONUrl = 'https://api.cedarmaps.com/v1/tiles/cedarmaps.streets.json?access_token=' + L.cedarmaps.accessToken;

    // initilizing map into div#map
    var map = L.cedarmaps.map('map', tileJSONUrl, {
        scrollWheelZoom: true
    }).setView([35.757448286487595, 51.40876293182373], 15);

</script>

Note: You can get an access token by filling out the demo account form in Cedarmaps Website.

If you prefer to have your local version of the libaray you can simply build it with the following commands:

Note: node.js must be installed on your machine.

git clone http://gitlab.cedar.ir/cedar.studios/cedarmaps-sdk-web-public.git
cd cedarmaps-sdk-web-public
npm install
grunt build

After the built process, the files are copied into dist/ folder according to current SDK version. (See package.json).

Note: Every time you pull new changes from repository, you should run grunt build again.

git pull
grunt build

The cedarmaps.js file includes the Leaflet library. Alternatively, you can use cedarmaps.standalone.js, which does not include Leaflet (you will have to provide it yourself).

Note: If you've purchased our dedicated plan you should set your baseURL in the following manner in <head> tag before including cedarmaps' files:

<script>
    apiBaseUrlHttp = 'http://your-own-api-url.com';
    apiBaseUrlHttps = 'https://your-own-api-url.com';
</script>

You can also see the API documentation and Mapbox's Examples for further help.

API

Cedarmaps' API is almost the same as mapbox's API. Check it out. However, Cedarmaps introduces some new API methods that are described below:

Forward Geocoding

For both forward and reverse geocofing functionality you should use L.cedarmaps.geocoder object.

L.cedarmaps.geocoder(id [, options])

A low-level interface to geocoding, useful for more complex uses and reverse-geocoding.

Options Value Description
id (required) String Currently only cedarmaps.streets
options (optional) Object If provided, it may include:
  • accessToken: Mapbox API access token. Overrides L.cedarmaps.accessToken for this geocoder.

Returns a L.cedarmaps.geocoder object.

Example:

var geocoder = L.cedarmaps.geocoder('cedarmaps.streets');

geocoder.query(queryString|options, callback)

Queries the geocoder with a query string, and returns the results, if any.

Options Value Description
queryString (required) string a query, expressed as a string, like 'Arkansas'
options object An object containing the query and options parameters like { query: 'ونک', limit: 5 }. Other available parameteres:

  • limit integer - Number of returned results. Default is 10, Max is 30
  • distance float - Unit is km, 0.1 means 100 meters
  • location lat,lon - For searching near a location. should be used only with distance param
  • type enum - Types of map features to filter the results. Possible values: locality, roundabout, street, freeway, expressway, boulevard
    (You can mix types by separating them with commas)
  • ne lat,lon - Specifies north east of the bounding box - should be used with sw param
  • sw lat,lon - Specifies south west of the bounding box - should be used with ne param
callback (required) function A callback with passed params: (error, result).

Returns a L.cedarmaps.geocoder object.

The results object's signature:

{
    status: // OK
    results: // raw results
}

Forward Geocoding Sample Code

Example: Check out a Live example of geocoder.query.

Using a single query parameter:

geocoder.query('ونک', function(err, res){});

Using query string along with an option (Limiting the number of results):

geocoder.query({query:'ونک', limit: 5}, function(err, res){});

Filtering results based on one or more feature types:

geocoder.query({query:'ونک', type: 'locality'}, function(err, res){});
geocoder.query({query:'ونک', type: 'locality,roundabout'}, function(err, res){});
geocoder.query({query:'ونک', type: 'street', limit:2}, function(err, res){});

Searching within in a specific bounding box:

geocoder.query({query:'لادن', ne: '35.76817388431271,51.41721725463867', sw: '35.75316460798604,51.39232635498047'}, function(err, res){});

Reverse Geocoding

geocoder.reverseQuery(location, callback)

Queries the reverse geocoder with a location object/array, and returns the address.

Options Value Description
location (required) object A query, expressed as an object:
  • [lon, lat] // an array of lon, lat
  • { lat: 0, lon: 0 } // a lon, lat object
  • { lat: 0, lng: 0 }
Note: This parameter can also be an array of objects in that form to geocode more than one item in a single request.
callback (required) function A callback with passed params: (error, result).

Returns: the geocoder object. The return value of this function is not useful - you must use a callback to get results.

Reverse Geocoding Sample Code

var geocoder = L.cedarmaps.geocoder('cedarmaps.streets');
geocoder.reverseQuery({lat: 35.754592526442465, lng: 51.401896476745605}, function callback(err, res){});

Example: Check out a Live example of reverseQuery.

Direction

Calculates a route between a start and end point (and optionally some middle points) up to 100 points in GeoJSON format:

Options Value Description
Profile (required) String Default and the only current available value: cedarmaps.driving.
LatLngs (required) String A pair of lat and lng points indicating start, middle and end, in format: lat,lng;lat,lng;[lat,lng...] (Up to 100 points)
callback (required) function A callback with passed params: (error, result).

Returns: the direction object. The return value of this function is not useful - you must use a callback to get the results.

Direction Sample Code

direction.route('cedarmaps.driving', '35.764335,51.365622;35.7604311,51.3939486;35.7474946,51.2429727', function(err, json) {
        var RouteGeometry = json.result.routes[0].geometry;

        var RouteLayer = L.geoJSON(RouteGeometry, {
            // for more styling options check out:
            // https://leafletjs.com/reference-1.3.0.html#path-option
            style: function(feature) {
                return {
                    color: '#f00',
                    weight: 5
                }
            }
        }).addTo(map);

        map.fitBounds(RouteLayer.getBounds());
    });
});

Example: Check out a Live example of Direction.

Administrative Boundaries Lister

administrativeBoundaries.query(type, query, callback)

Lists administrative boundaries in 3 different levels: province, city, locality (aka. neighborhood).

Options Value Description
type (required) string Type of an administrative boundary. Possible values: province, city, locality.
query (optional) string The query to limit the type above. For example: list all cities of "Tehran" province: query('city', 'تهران', function(){}). This option is not neccessary for type: province as it has no parents.
callback (required) function A callback with passed params: (error, result).

Returns: the L.cedarmaps.administrativeBoundaries object.

Administrative Boundaries Lister Sample Code

var administrativeLister = L.cedarmaps.administrativeBoundaries();
    // Get list of all provinces of Iran.
    administrativeLister.query('province', '', function(err, res){});
    // Get list of cities of Tehran Province.
    administrativeLister.query('city', 'تهران', function(err, res){});

Example: Check out a Live example of address locator.

Updating SDK

In case of any updates in module itself the following files must be updated: