Cedarmaps Web SDK (Raster Tiles)

CedarMaps address locator tool

CedarMaps Web SDK (JS) is a javascript library for building interactive maps. It's built on top of Mapbox Javascript API, (The current version is v3.1.1). It uses Leaflet.js for map interactinons so you can use all of this library's methods for your purpose.

Note: This repo is for "raster tiles". If you prefer to use our "vector tiles" please visit: https://github.com/cedarstudios/cedarmaps-web-sdk-vector

Basic usage via CDN
Checking out demo files
Building SDK locally
Pulling new changes from repo
API
Upgrading SDK
Issues

Basic usage via CDN

Get an access token from Cedar Maps website (Menu link: "درخواست اکانت رایگان"). It may take a couple of hours until your request is processed and your credentials are emailed to you.

Include these 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' />

Put the following code in the <body> of your HTML file:
`html


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

// Setting up our layer
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>


# Checking out demo files
In order to check out demo files in `/demos` folder you need to build the SDK locally or change the script and css paths to our CDN ones mentioned above. 

# Building SDK locally
1. Clone this repo:
```sh
git clone https://github.com/cedarstudios/cedarmaps-web-sdk-raster

In the root folder of your cloned repo make a new file called access-token.js and put your access token in it:
```
var accessToken = 'YOUR_ACCESS_TOKEN';
```
Install the required backages: (You have to have Node.js and npm installed on your machine.)
```
npm install
```
Build the SDK. It stores the files in /dist/[sdk-version] folder. (See package.json).

grunt build

Go to /demos folder and pick one for the start.

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>

Pulling new changes from repo

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

git pull
grunt build

API

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

Forward & Reverse Geocoding

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

Initializing Forward/Reverse Geocoder

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

Before using forward/reverse Geocoder object, you must initialize it using the desired profile (id).

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');

Forward Geocoder

Signature: 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 Geocoder 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

Signature: 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

Signature: 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.

Upgrading SDK

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

version in ./package.json
version in <script> and <link> tags in demo files (./demo)
version in sample API usage in README.md
"Doc files" by running grunt doc command
building new dist files by running grunt build command

Issues

If you have any questions while implementing Cedar Maps Web SDK, please feel free to open a new issue.