This is CedarMaps Javascript API. It's simply a wrapper for [Mapbox Javascript API](https://github.com/mapbox/mapbox.js/), (Currently `v2.2.3`) which is itself built as a [Leaflet](http://leafletjs.com/) plugin. You can [read about its launch](http://mapbox.com/blog/mapbox-js-with-leaflet/).
CedarMaps JS is a javascript library for building interactive maps. It's simply a wrapper for [Mapbox Javascript API](https://github.com/mapbox/mapbox.js/), (The current version is `v3.1.1`) which is itself built as a [Leaflet](http://leafletjs.com/) plugin. You can [read about its launch](http://mapbox.com/blog/mapbox-js-with-leaflet/).
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).
and put the following code in the `<body>` of your HTML file:
cedarmaps APIs only work with a valid "Acces Token". You must set your access token to `L.cedarmaps.accessToken` variable like this:
Check out demos at `demos/` folder for better grasping the idea.
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.
```sh
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:
...
...
@@ -45,43 +75,43 @@ Check out demos at `demos/` folder for better grasping the idea.
You can also see the [API documentation](http://mapbox.com/mapbox.js/api/) and [Mapbox's Examples](http://mapbox.com/mapbox.js/example/v1.0.0/) for further help.
## API
# API
API is almost the same as mapbox's API. [Check it out](http://mapbox.com/mapbox.js/api/).
However two mostly used methods: forward and reverse geocoding APIs are described below for easy access:
Cedarmaps' API is almost the same as mapbox's API. [Check it out](http://mapbox.com/mapbox.js/api/). However, Cedarmaps introduces some new API methods that are described below:
## Forward/Reverse Geocoding
## Forward Geocoding
For both forward and reverse geocofing functionality you should use `L.cedarmaps.geocoder` object.
### L.cedarmaps.geocoder(id, options)
### `L.cedarmaps.geocoder(id [, options])`
A low-level interface to geocoding, useful for more complex uses and reverse-geocoding.
| Options | Value | Description |
| ---- | ---- | ---- |
| id | string | currently `cedarmaps.streets` |
| options | Object | The second argument is optional. If provided, it may include: <ul><li>`accessToken`: Mapbox API access token. Overrides `L.cedarmaps.accessToken` for this geocoder.</li></ul> |
| id (_required_) | String | Currently only `cedarmaps.streets` |
| options (_optional_) | Object | If provided, it may include: <ul><li>`accessToken`: Mapbox API access token. Overrides `L.cedarmaps.accessToken` for this geocoder.</li></ul> |
Queries the geocoder with a query string, and returns its result, if any.
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 }`. <br/><br/>Other available parameteres: <br/><br/><ul><li>`limit`*integer* - Max is 30</li><li>`distance`*float* - Unit is km, 0.1 means 100 meters</li><li>`location`*lat,lon* - For searching near a location. should be accompanied with distance param</li><li>`type`*enum* - Possible values: `locality`, `roundabout`, `street`, `freeway`, `expressway`, `boulevard`<br/>(You can mix types by separating them with comma)</li><li>`ne`*lat,lon* - Specifies north east of the bounding box - should be accompanied with `sw` param</li><li>`sw` lat,lon - Specifies south west of the bounding box - should be accompanied with `ne` param</li></ul> |
| callback (_required_) | function | a callback |
| options | object | An object containing the query and options parameters like `{ query: 'ونک', limit: 5 }`. Other available parameteres: <br/><br/><ul><li>`limit`*integer* - Number of returned results. Default is `10`, Max is `30`</li><li>`distance`*float* - Unit is km, `0.1` means 100 meters</li><li>`location`*lat,lon* - For searching near a location. should be used only with distance param</li><li>`type`*enum* - Types of map features to filter the results. Possible values: `locality`, `roundabout`, `street`, `freeway`, `expressway`, `boulevard`<br/>(You can mix types by separating them with commas)</li><li>`ne`*lat,lon* - Specifies north east of the bounding box - should be used with `sw` param</li><li>`sw` lat,lon - Specifies south west of the bounding box - should be used with `ne` param</li></ul> |
| callback (_required_) | function | A callback with passed params: `(error, result)`. |
_Returns_ a `L.cedarmaps.geocoder` object.
The callback is called with arguments
The results object's signature:
1. An error, if any
2. The result. This is an object with the following members:
```javascript
{
status:// OK
...
...
@@ -89,83 +119,72 @@ The callback is called with arguments
}
```
_Example_: [Live example of geocoder.query centering a map.](http://www.cedarmaps.com/websdk/demos/geocoder-control.html)
_Returns_: the geocoder object. The return value of this function is not useful - you must use a callback to get results.
### Forward Geocoding Sample Codes
_Example_: Check out a [Live example of geocoder.query](https://demo.cedarmaps.com/websdk/demos/geocoder-control.html).
#### Geocoding Examples:
using a single query parameter:
Using a single query parameter:
```javascript
geocoder.query('ونک',function(err,res){});
```
using query string along with an option (Limiting the results):
Using query string along with an option (Limiting the number of results):
Queries the geocoder with a location, and returns its result, if any.
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:<ul><li>`[lon, lat] // an array of lon, lat`</li><li>`{ lat: 0, lon: 0 } // a lon, lat object`</li><li>`{ lat: 0, lng: 0 } // a lng, lat object`</li></ul> The first argument can also be an array of objects in that form to geocode more than one item. |
| callback (_required_) | function | The callback is called with arguments - An error, if any - The result. This is an object of the raw result from Mapbox. |
| location (_required_) | object | A query, expressed as an object:<ul><li>`[lon, lat] // an array of lon, lat`</li><li>`{ lat: 0, lon: 0 } // a lon, lat object`</li><li>`{ lat: 0, lng: 0 } `</li></ul>**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.
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`. |
| callback (_required_) | function | The callback is called with arguments - An error, if any - The result. |
| 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 administrativeBoundaries object. The return value of this function is not useful - you must use a callback to get results.
_Returns_: the `L.cedarmaps.administrativeBoundaries` object.
white-space:-moz-pre-wrap;/* Mozilla, since 1999 */
white-space:-pre-wrap;/* Opera 4-6 */
white-space:-o-pre-wrap;/* Opera 7 */
word-wrap:break-word;/* Internet Explorer 5.5+ */
}
</style>
</head>
<body>
<divid='map'class='map'></div>
<divid="results">
<h2>Click somewhere on map!</h2><divid="loading"><imgsrc="../dist/v1.7.0/images/loading-14-white.gif"width="14"height="14"> Loading...</div>
<h2style="text-align: center;">Click somewhere on the map!</h2><divid="loading"><imgsrc="../dist/v1.7.0/images/loading-14-blue.gif"width="14"height="14"> Loading...</div>
