API Documentation
API Documentation
If you don't want to use our SDKs, you can call all CedarMaps API methods using a simple HTTP client in your preferred language. All response formats are in JSON.
We suggest to use a simple command line HTTP client such as httpie to run samples.
You should have a client_id and client_secret in order to get an access_token.
Request:
http --form POST "https://api.cedarmaps.com/v1/token" client_id=<client_id> client_secret=<client_secret> -v
Response:
Includes access_token
Request:
http --form POST "https://api.cedarmaps.com/v1/token" client_id=taxiyaab-demo-5219036277852975494 client_secret=VfqCKHRheGl5YWFiLWRlbW-C-c63wpGC2OOVI6NEXPoUwO98eq3f8EtD21KXQJFPkA== -v
Response:
{
"access_token": "2192ad1e2821d1104b431cd42c40b3cde410bac8",
"expires_in": 604800,
"scope": null,
"token_type": "bearer"
}
Forward Geocoding is done on a specific {index} such as cedarmaps.streets. {query} should be URL-encoded text.
Caution:
This API call needs a valid access token.
The only supported `index` is `cedarmaps.streets`
Access token can be either passed via query string:
https://api.cedarmaps.com/v1/geocode/{index}/{query}.json?access_token=<your access token>
or http header:
http "https://api.cedarmaps.com/v1/geocode/{index}/{query}.json" "Authorization: Bearer <your access token>"
There's also other filters available for this method call that can be appended to query string:
| Param | Type | Description |
|---|---|---|
| limit | integer | Max is 30 |
| distance | float | Unit is km, 0.1 means 100 meters |
| location | lat,lon | Center point of a nearby search. should be accompanied with distance param |
| type | enum | Possible values are: locality, roundabout, street, freeway, expressway, boulevard, city, state (You can mix types by separating them with commas) |
| ne | lat,lon | Specifies north east of the bounding box - should be accompanied with sw param |
| sw | lat,lon | Specifies south west of the bounding box - should be accompanied with ne param |
Existence of ne/sw are prioritized over location/distance pair.
Request:
http "https://api.cedarmaps.com/v1/geocode/cedarmaps.streets/همت?limit=2&access_token=<your access token>"
Response:
{
"results": [
{
"address": "اراضی عباس آباد,مهران,سید خندان,...",
"components": {
"city": "تهران",
"country": "ایران",
"districts": [
"منطقه 4",
"منطقه 3"
],
"localities": [
"اراضی عباس آباد",
"مهران",
"سید خندان",
"پاسداران"
],
"province": "تهران"
},
"id": 429874,
"location": {
"bb": {
"ne": "35.756689799999997,51.464761500000002",
"sw": "35.7491463,51.423702800000001"
},
"center": "35.749155599171999,51.428327751596903"
},
"name": "همت",
"type": "expressway"
},
{
"address": "المهدی",
"components": {
"city": "تهران",
"country": "ایران",
"districts": [
"منطقه 5"
],
"localities": [
"المهدی"
],
"province": "تهران"
},
"id": 338756,
"location": {
"bb": {
"ne": "35.770861600000003,51.323841700000003",
"sw": "35.770540400000002,51.323066400000002"
},
"center": "35.770585227006897,51.323426168064202"
},
"name": "همت",
"type": "street"
}
],
"status": "OK"
}
Request: (Using type parameter)
http "https://api.cedarmaps.com/v1/geocode/cedarmaps.streets/ونک?type=locality,roundabout&limit=2&access_token=<your access token>"
Response:
{
"results": [
{
"address": "",
"components": {
"city": "تهران",
"country": "ایران",
"districts": [
"منطقه 3"
],
"localities": [],
"province": "تهران"
},
"id": 430595,
"location": {
"bb": {
"ne": "35.787902600000002,51.396891400000001",
"sw": "35.750329600000001,51.386025500000002"
},
"center": "35.7643093874984,51.391913977109297"
},
"name": "ونک",
"type": "locality"
},
{
"address": "کاووسیه",
"components": {
"city": "تهران",
"country": "ایران",
"districts": [
"منطقه 3"
],
"localities": [
"کاووسیه"
],
"province": "تهران"
},
"id": 355549,
"location": {
"bb": {
"ne": "35.757941899999999,51.410466800000002",
"sw": "35.757091199999998,51.409414099999999"
},
"center": "35.757519575295198,51.409940758141303"
},
"name": "میدان ونک",
"type": "roundabout"
}
],
"status": "OK"
}
Request: (Using ne,sw parameters)
http "https://api.cedarmaps.com/v1/geocode/cedarmaps.streets/لادن?ne=35.76817388431271,51.41721725463867&sw=35.75316460798604,51.39232635498047&access_token=<your access token>"
Response:
{
"results": [
{
"address": "آرارات",
"components": {
"city": "تهران",
"country": "ایران",
"districts": [
"منطقه 3"
],
"localities": [
"آرارات"
],
"province": "تهران"
},
"id": 355344,
"location": {
"bb": {
"ne": "35.759898499999998,51.399152800000003",
"sw": "35.759766300000003,51.397399"
},
"center": "35.759832400000001,51.398275900000002"
},
"name": "لادن",
"type": "street"
}
],
"status": "OK"
}
Request: (Using location,distance parameters)
http "https://api.cedarmaps.com/v1/geocode/cedarmaps.streets/لادن?location=35.75939850274211,51.397433280944824&distance=.1&access_token=<your access token>"
Response:
{
"results": [
{
"address": "آرارات",
"components": {
"city": "تهران",
"country": "ایران",
"districts": [
"منطقه 3"
],
"localities": [
"آرارات"
],
"province": "تهران"
},
"id": 355344,
"location": {
"bb": {
"ne": "35.759898499999998,51.399152800000003",
"sw": "35.759766300000003,51.397399"
},
"center": "35.759832400000001,51.398275900000002"
},
"name": "لادن",
"type": "street"
}
],
"status": "OK"
}
It gives you an address based on a provided LatLng pair.
Caution:
This API call needs a valid access token.
The only supported `index` is `cedarmaps.streets`
point format is lat,lon
http https://api.cedarmaps.com/v1/geocode/{index}/{point}.json?access_token=<your access token>
OR:
http "https://api.cedarmaps.com/v1/geocode/{index}/{point}.json" "Authorization: Bearer <your access token>"
Request:
http https://api.cedarmaps.com/v1/geocode/cedarmaps.streets/35.716482704636825,51.40897750854492.json?access_token=<your access token>
Response:
{
"result": {
"address": "بن بست سروش - زرتشت",
"city": "تهران",
"components": [
{
"long_name": "بن بست سروش",
"short_name": "بن بست سروش",
"type": "residential"
},
{
"long_name": "زرتشت",
"short_name": "زرتشت",
"type": "primary"
},
{
"long_name": "بهجت آباد",
"short_name": "بهجت آباد",
"type": "locality"
},
{
"long_name": "منطقه ۶",
"short_name": "منطقه ۶",
"type": "district"
},
{
"long_name": "تهران",
"short_name": "تهران",
"type": "city"
},
{
"long_name": "تهران",
"short_name": "تهران",
"type": "province"
},
{
"long_name": "ایران",
"short_name": "ایران",
"type": "country"
},
{
"long_name": "مجتمع مسکونی بهجت آباد",
"short_name": "مجتمع مسکونی بهجت آباد",
"type": "place"
}
],
"country": "ایران",
"district": "منطقه ۶",
"locality": "بهجت آباد",
"place": "مجتمع مسکونی بهجت آباد",
"province": "تهران",
"traffic_zone": {
"in_central": true,
"in_evenodd": true,
"name": "محدوده طرح ترافیک"
}
},
"status": "OK"
}
This method calculates the distance between points in meters. It can be called with up to 100 different points in a single request.
Point pairs format are as below
lat1,lon1;lat2,lon2
The first is starting point and the latter is ending point. For batch mode they can be separated by /
The only supported profile is cedarmaps.driving which calculates the distance using car routing.
Single mode:
Given that pair is lat1,lon1;lat2,lon2
https://api.cedarmaps.com/v1/distance/cedarmaps.driving/{pair}?access_token=<your access token>
Batch mode: (Up to 100 pairs)
pair is lat1,lon1;lat2,lon2
https://api.cedarmaps.com/v1/distance/cedarmaps.driving/{pair1}/{pair2}/../{pair100}?access_token=<your access token>
Response elements:
| Param | Description |
|---|---|
| distance | The overall distance of the route, in meter |
| time | The overall time of the route, in ms |
| bbox | The bounding box of the route, format: minLon, minLat, maxLon, maxLat |
Single mode request:
http "https://api.cedarmaps.com/v1/distance/cedarmaps.driving/35.75882,51.415703;35.759148,51.379848?access_token=<your access token>"
Single mode response:
{
"result": {
"routes": [
{
"bbox": [
51.368587,
35.74982,
51.41652,
35.762383
],
"distance": 7516.338,
"time": 500912
}
]
},
"status": "OK"
}
Batch mode request:
http "https://api.cedarmaps.com/v1/distance/cedarmaps.driving/35.75882,51.415703;35.759148,51.379848/35.759148,51.379848;35.75882,51.41573?access_token=<your access token>"
Batch mode response:
{
"result": {
"routes": [
{
"bbox": [
51.368587,
35.74982,
51.41652,
35.762383
],
"distance": 7516.338,
"time": 500912
},
{
"bbox": [
51.367825,
35.749058,
51.415726,
35.762383
],
"distance": 8106.386,
"time": 522081
}
]
},
"status": "OK"
}
This method calculates the optimal driving routes between two or more points.
Point pairs format are as below. A semicolon-separated list of {latitude},{longitude} coordinate pairs to visit in order, containing at least two elements (origin and destination).
lat1,lon1;lat2,lon2
The only supported profile is cedarmaps.driving which calculates the distance using car routing. This profile shows the fastest routes by preferring high-speed roads like highways.
Given that pair is lat1,lon1;lat2,lon2
https://api.cedarmaps.com/v1/direction/cedarmaps.driving/{pair}?access_token=<your access token>
Response elements:
| Param | Description |
|---|---|
| distance | The overall distance of the route, in meter |
| time | The overall time of the route, in ms |
| bbox | The bounding box of the route, format: minLon, minLat, maxLon, maxLat |
| geometry | The geometry of the route as a GeoJSON LineString |
http "https://api.cedarmaps.com/v1/direction/cedarmaps.driving/35.764335,51.365622;35.763316,51.365322?access_token=<your access token>"
{
"result": {
"routes": [
{
"bbox": [
51.36444,
35.76323,
51.365623,
35.76432
],
"distance": 244.929,
"geometry": {
"coordinates": [
[
51.365623,
35.76432
],
[
51.365257,
35.764303
],
[
51.364963,
35.764235
],
[
51.364673,
35.764141
],
[
51.364442,
35.764025
],
[
51.364884,
35.763525
],
[
51.364888,
35.763482
],
[
51.365049,
35.763228
],
[
51.36532,
35.76332
]
],
"type": "LineString"
},
"time": 22602
}
]
},
"status": "OK"
}
In order to get turn-by-turn instructions you should include instructions=true parameter in query string.
https://api.cedarmaps.com/v1/direction/cedarmaps.driving/{pair}?instructions=true&access_token=<your access token>
Response elements:
| Param | Description |
|---|---|
| instructions | Instructions for this route. The last instruction is always the Finish instruction and takes 0ms and 0meter |
| instructions[].text | A description what the user has to do in order to follow the route |
| instructions[].street_name | The name of the street to turn onto in order to follow the route |
| instructions[].distance | The distance for this instruction, in meter |
| instructions[].time | The duration for this instruction, in ms |
| instructions[].interval | An array containing the first and the last index (relative to geometry.coordinates) of the points for this instruction. This is useful to know for which part of the route the instructions are valid |
| instructions[].sign | A number which specifies the sign to show
|
Request:
http "https://api.cedarmaps.com/v1/direction/cedarmaps.driving/35.73846015607031,51.43755359575154;35.73804799771853,51.43421173095704?access_token=<your access token>&instructions=true"
Response:
{
"result": {
"routes": [
{
"bbox": [
51.43418,
35.738007,
51.43793,
35.738693
],
"distance": 570.586,
"geometry": {
"coordinates": [
[
51.437536,
35.738675
],
[
51.437901,
35.738695
],
[
51.43793,
35.738142
],
[
51.435609,
35.738006
],
[
51.435563,
35.738689
],
[
51.434183,
35.738635
],
[
51.434204,
35.738048
]
],
"type": "LineString"
},
"instructions": [
{
"distance": 32.977,
"heading": 86.21,
"interval": [
0,
1
],
"sign": 0,
"street_name": "دهم",
"text": "تا دهم ادامه دهید",
"time": 4748
},
{
"distance": 61.447,
"interval": [
1,
2
],
"sign": 2,
"street_name": "سیبویه",
"text": " به راست بپیچید به سیبویه",
"time": 4915
},
{
"distance": 210.041,
"interval": [
2,
3
],
"sign": 2,
"street_name": "هشتم",
"text": " به راست بپیچید به هشتم",
"time": 30245
},
{
"distance": 76.09,
"interval": [
3,
4
],
"sign": 2,
"street_name": "عربعلی",
"text": " به راست بپیچید به عربعلی",
"time": 6085
},
{
"distance": 124.698,
"interval": [
4,
5
],
"sign": -2,
"street_name": "نهم",
"text": " به چپ بپیچید به نهم",
"time": 17956
},
{
"distance": 65.334,
"interval": [
5,
6
],
"sign": -2,
"street_name": "رهبر",
"text": " به چپ بپیچید به رهبر",
"time": 9408
},
{
"distance": 0.0,
"interval": [
6,
6
],
"last_heading": 178.3159250006148,
"sign": 4,
"street_name": "",
"text": "پایان!",
"time": 0
}
],
"time": 73357
}
]
},
"status": "OK"
}
TileJSON is a format that manages the complexities of custom maps. It organizes zoom levels, center points, legend contents, and more, into a format that makes it easy to display a map.
Cedarmaps provide a separate TileJSON for each of its {mapid}s.
Get it either by:
https://api.cedarmaps.com/v1/tiles/{mapid}.json?access_token=<your access token>
OR:
http GET "https://api.cedarmaps.com/v1/tiles/cedarmaps.streets.json" "Authorization: Bearer <your access token>" -v
A sample of returned tileJSON is as follows:
{
"bounds": [
44,
24.6,
63.4,
39.8
],
"description": "CedarMaps covering the whole country of Iran",
"maxzoom": 17,
"minzoom": 6,
"name": "CedarMaps Streets",
"tilejson": "2.3.0",
"tiles": [
"https://api.cedarmaps.com/v1/tiles/cedarmaps.streets/{z}/{x}/{y}.png?access_token=<your access token>"
],
"version": "2.0"
}
After loading the above TileJSON, it gives you the path to load the tiles:
https://api.cedarmaps.com/v1/tiles/{mapid}/{z}/{x}/{y}.png?access_token=<your access token>