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
- 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.1/cedarmaps.js"></script>
<link
href="https://api.cedarmaps.com/cedarmaps.js/v1.8.1/cedarmaps.css"
rel="stylesheet"
/>- Put the following code in the of your HTML file:
<!-- Make a div with id "map" and set its dimensions -->
<div id="map" style="width: 400px; height: 300px;"></div>
<script type="text/javascript">
// In order to use Cedar Maps you **MUST** have an access token
L.cedarmaps.accessToken = "YOUR_ACCESS_TOKEN";
// 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>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.
- Clone this repo:
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.jsand put your access token in it:
var accessToken = 'YOUR_ACCESS_TOKEN';
npm install
- Build the SDK. It stores the files in
/dist/[sdk-version]folder. ([sdk-version]is determined byversioninpackage.json).
npm run build
- Go to
/demosfolder 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>Every time you pull new changes from repository, you should run grunt build again.
git pull
grunt buildCedarmaps' API is almost the same as mapbox. Check it out. However, Cedarmaps introduces some new API methods that are described below:
For both forward and reverse geocofing functionality you should use L.cedarmaps.geocoder object.
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 | Available profiles:
|
| options (optional) | Object | If provided, it may include:
|
Returns a L.cedarmaps.geocoder object.
Example:
var geocoder = L.cedarmaps.geocoder("cedarmaps.streets");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:
|
| 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
}Example: Check out a Live example of geocoder.query. If you want more control over your searchbox rendering, please check out another example implementing a custom seachbox with a third-party auto complete library.
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) {}
);Signature: geocoder.reverseQuery(location, callback)
Queries the reverse geocoder with a location and returns the address in desired format.
| Options | Value | Description |
|---|---|---|
| location (required) | Mixed |
|
| callback (required) | Function | A callback with passed params: (error, result). |
Returns: the geocoder object. The return value may not come handy since it runs asynchronously and you must use a callback to get the results.
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.
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.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.
Lists administrative boundaries in 3 different levels: province, city, locality (aka. neighbourhood).
Signature: administrativeBoundaries.query(type, query, callback)
| 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(error, result){}). 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.
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.
CedarMaps is integrated with its sister project kikojas.com and has access to all of the curated POIs available in it. It gives you the ability to query public places near a certain point on map. The available categories are:
- Parks
- Bus Stations
- Shopping Malls
- Hospitals
- Schools
Note: You may purchase the availability of other categories for your project. Please contact us for more information.
Signature: L.cedarmaps.nearby(mapContainer, centerPoint, {options})
| Options | Value | Description |
|---|---|---|
| categories (required) | Array | List of categories you want to have in your map. Available options are bus, park, shopping, hospital and school |
| searchDistance (optional) | Float | Distance radius to search for POIs, in Kilometer. For 500 meters use 0.5. |
| popupContent (required) | Function | A callback with passed params: (error, result). |
| centerMarkerIcon (optional) | Leaflet Marker | You may use your custom leaflet marker for your central point. Example: window.L.icon({"slug":"@default","iconUrl":"https://api.cedarmaps.com/v1/markers/marker-default.png","iconRetinaUrl":"https://api.cedarmaps.com/v1/markers/marker-default@2x.png","iconSize":[82,98]}) |
| popupContent (optional) | String | Popup content for centralMarker. Can contain HTML code. |
| defaultZoom (optional) | Integer | Your desired zoom level for map. |
Example: Check out a Live example of nearby widget.
If you don't want to include a bunch of script tags into your HTML and just need an image showing a map with a marker representing a point on it, you may use this API.
Signature: L.cedarmaps.staticMap({options})
| Options | Value | Description |
|---|---|---|
| maptype (required) | String | The only available profile is light for now. |
| position (required) | String | The center point and zoom level with which map should be generated, in format: lat,lng,zoom (e.g.: 35.791124154289,51.415790319443,13). If your generated image has markers on it and they should be fit in your map, use value auto. |
| dimension (required) | String | Dimension of the generated image in format: widthxheight. (e.g.: 800x600). Either values for width and height should not exceed 1280 pixels. |
| scale (optional) | String | For retina displays with more pixels density use this option. It doubles the size for both maps and markers. |
| markers (optional) | String | For adding optional markers on the map, in format: marker-name|lat,lng. (e.g.: marker-circle-orange|35.79,51.41|marker-default|35.83,51.45). Here, marker-circle-orange and marker-default are from CedarMaps preset marker names. You may use your own custom markers by providing their absolute url path starting with http://. Note: If you request for a static map with your custom marker URL, the first request caches the marker image and the second request actually responds with your static map. Available marker presents are:
|
Example: Check out a Live example of static image generator.
In case of any updates in module itself the following files must be updated:
versionin./package.jsonversionin<script>and<link>tags in demo files (./demo)versionin sample API usage inREADME.md- "Doc files" by running
grunt doccommand - building new dist files by running
grunt buildcommand
If you have any questions while implementing Cedar Maps Web SDK, please feel free to open a new issue.