{"id":24658538,"url":"https://github.com/cedarstudios/cedarmaps-nodejs-client","last_synced_at":"2025-03-21T05:12:58.481Z","repository":{"id":57195594,"uuid":"138480296","full_name":"cedarstudios/cedarmaps-nodejs-client","owner":"cedarstudios","description":"A node.js and browser JavaScript client to CedarMaps services.","archived":false,"fork":false,"pushed_at":"2019-10-13T10:56:44.000Z","size":50,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-17T21:00:01.390Z","etag":null,"topics":["cedarmaps","forward-geocoding","iran","map","reverse-geocode"],"latest_commit_sha":null,"homepage":"https://www.cedarmaps.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cedarstudios.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-06-24T12:32:10.000Z","updated_at":"2019-10-13T10:56:45.000Z","dependencies_parsed_at":"2022-09-16T12:12:32.652Z","dependency_job_id":null,"html_url":"https://github.com/cedarstudios/cedarmaps-nodejs-client","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cedarstudios%2Fcedarmaps-nodejs-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cedarstudios%2Fcedarmaps-nodejs-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cedarstudios%2Fcedarmaps-nodejs-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cedarstudios%2Fcedarmaps-nodejs-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cedarstudios","download_url":"https://codeload.github.com/cedarstudios/cedarmaps-nodejs-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244739960,"owners_count":20501992,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cedarmaps","forward-geocoding","iran","map","reverse-geocode"],"created_at":"2025-01-26T01:37:54.544Z","updated_at":"2025-03-21T05:12:58.461Z","avatar_url":"https://github.com/cedarstudios.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cedarmaps\nA [node.js](https://nodejs.org/) and browser JavaScript client to CedarMaps services.\n\n# Table of contents\n- [Installation](#installation)\n- [API](#api)\n  * [Forward Geocoder](#forward-geocoder)\n  * [Reverse Geocoder](#reverse-geocoder)\n  * [Trip Calculator](#trip-calculator)\n  * [Turn by Turn Navigation](#turn-by-turn-navigation)\n  * [TileJSON](#tilejson)\n- [Issues](#issues)\n\n# Installation\n```\n$ npm i @cedarstudios/cedarmaps\n```\n\nIn order to use CedarMaps' API, you **MUST** have an access token. Get one from [CedarMaps](https://www.cedarmaps.com/) website (Menu link: \"درخواست اکانت رایگان\"). It may take a couple of hours until your request is processed and your credentials are emailed to you.\n\n```javascript\nconst cedarMaps = require('@cedarstudios/cedarmaps');\nconst client = cedarMaps('\u003cYOUR ACCESS TOKEN\u003e'); // Get your token from cedarmaps.com\n```\n\n# API\n## Forward Geocoder\nSignature: `client.forwardGeocoding(queryString, searchIndex, filters, callback)`\n\n| Options | Value | Description |\n|--------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| queryString (_required_) | String | a query, expressed as a string, like 'ونک'. This string **MUST** be URI encoded. Use `encodeURIComponent('ونک')` for example. |\n| searchIndex (_required_) | String | Available profiles: \u003cul\u003e\u003cli\u003e `cedarmaps.streets` Only searches through map features - 1 API Call\u003c/li\u003e\u003cli\u003e `cedarmaps.places` Only searches through places (Source: [kikojas.com](https://www.kikojas.com)) - 2 API Calls\u003c/li\u003e\u003cli\u003e `cedarmaps.mix` Searches through both profiles above - 3 API Calls\u003c/li\u003e\u003c/ul\u003e |\n| filters | Object | Example: `{ distance: 0.5, limit: 5 }`. \u003cbr /\u003eAvailable filters:  \u003cul\u003e\u003cli\u003e`limit` *integer* - Number of returned results. Default is `10`, Max is `30`.\u003c/li\u003e\u003cli\u003e`distance` *float* - Unit is km, `0.1` means 100 meters.\u003c/li\u003e\u003cli\u003e`location` *lat,lng* - For searching near a location. should be used only with `distance` param.\u003c/li\u003e\u003cli\u003e`type` *enum* - Types of map features to filter the results. Possible values: `street`, `poi`, `village`, `roundabout`, `expressway`, `locality`, `town`, `city`, `junction`, `freeway`, `boulevard`, `region`, `state` \u003cbr /\u003e(You can mix types by separating them with commas).\u003c/li\u003e\u003cli\u003e`ne` *lat,lng* - Specifies north east of the bounding box - should be used with `sw` param.\u003c/li\u003e\u003cli\u003e`sw` lat,lng - Specifies south west of the bounding box - should be used with `ne` param.\u003c/li\u003e\u003c/ul\u003e |\n| callback (_required_) | Function | A callback with passed params: `(error, result)`. |\n\nSample usage:\n\n```js\nclient.forwardGeocoding(encodeURIComponent('ونک'), 'cedarmaps.streets', {type: 'roundabout'}, (err, res) =\u003e {console.log(res);});\n```\n\n## Reverse Geocoder\nSignature: `client.reverseGeocoding(location, options, callback)`\n\nQueries the reverse geocoder with a location and returns the address in desired format.\n\n| Options | Value | Description |\n|-----------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| location (_required_) | Mixed | A point can be formatted in one of the forms below:\u003cul\u003e\u003cli\u003e`[lon, lat] // an array of lon, lat`\u003c/li\u003e\u003cli\u003e`{ lat: 0, lon: 0 } // a lon, lat object`\u003c/li\u003e\u003cli\u003e`{ lat: 0, lng: 0 } `\u003c/li\u003e\u003c/ul\u003e  |\n| options | Object | \u003cul\u003e\u003cli\u003e`format` - Address format with a number of place holders. Example: `{province}{sep}{city}{sep}{locality}{sep}{district}{sep}{address}{sep}{place}` \u003c/li\u003e\u003cli\u003e`Prefix` - Possible values: `short`, `long`\u003c/li\u003e\u003cli\u003e`Separator` - Character for `{sep}` placeholder. Example: `\"، \"`\u003c/li\u003e\u003cli\u003e`Verbosity` - Either `true` or `false`\u003c/li\u003e\u003c/ul\u003e |\n| callback (_required_) | Function | A callback with passed params: `(error, result)`. |\n\nSample usage:\n\n```js\nclient.reverseGeocoding([35.76312468, 51.40292645], {verbosity: true}, (err, res) =\u003e { console.log(res) });\n```\n\n## Trip Calculator\nSignature: `client.distance(points, callback)`\n\nTravel-time and distance between up to **100** pairs of origin and destination, in one single request.\n\n| Options | Value | Description |\n|-----------------------|----------|---------------------------------------------------|\n| points (_required_) | Array | An Array of {lat,lon} pairs. Example: `[{ lat: 35.76312468, lon: 51.40292645 }, { lat: 35.76288091, lon: 51.37305737}]` |\n| callback (_required_) | Function | A callback with passed params: `(error, result)`. |\n\nReponse object description: \n\n| Key | Description |\n| ---- | ---- |\n| distance | The total distance of the route, in Meters. |\n| time | The total time of the route, in Milliseconds. |\n| bbox | The bounding box of the route, format: minLon, minLat, maxLon, maxLat. |\n\nSample usage:\n\n```js\nclient.distance([{ lat: 35.76312468, lon: 51.40292645 }, { lat: 35.76288091, lon: 51.37305737}], (err, res) =\u003e {console.log(res)});\n```\n\n## Turn by Turn Navigation\nSignature: `client.direction(points, options, callback)`\n\nCalculates the optimal driving routes between two or more points. (Shortest path)\n\n\n**Note**: The number of provided points must be even.\n\n| Options | Value | Description |\n|-----------------------|----------|-------------------------------------------------------------------------------------------------------------------------|\n| points (_required_) | Array | An Array of {lat,lon} pairs. Example: `[{ lat: 35.76312468, lon: 51.40292645 }, { lat: 35.76288091, lon: 51.37305737}]` |\n| options | Object | The only available option for now is `instructions` (*Boolean*) which adds driving instructions object to the response. |\n| callback (_required_) | Function | A callback with passed params: `(error, result)`. |\n\nSample usage:\n\n```js\nclient.direction([{ lat: 35.76312468, lon: 51.40292645 }, { lat: 35.76288091, lon: 51.37305737 }], {instructions: true}, (err, res) =\u003e { console.log(err, res) })\n```\nReponse object description: \n\n| Key | Description |\n| ---- | ---- |\n| distance | The total distance of the route, in Meters. |\n| time | The total time of the route, in Milliseconds. |\n| bbox | The bounding box of the route, format: minLon, minLat, maxLon, maxLat. |\n| geometry | The geometry of the route as a GeoJSON LineString. |\n\nHere's the `intructions` object description:\n\n**Note:** The last item in instructions array is the stop item with `distance` and `time` values of `0`.\n\n| Key | Description |\n|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| text | Descriptive text of the instruction. |\n| street_name | The name of the street to turn onto in order to follow the route. |\n| distance | The distance for this instruction, in Meters. |\n| time | The duration for this instruction, in Milliseconds. |\n| 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. |\n| sign | A number representing actions that should be taken to follow the instructions. You may use this number for determining the action icon in your interface, or voice instructions, etc.: \u003cul\u003e\u003cli\u003eKeep Left=-7\u003c/li\u003e \u003cli\u003eTurn Sharp Left = -3\u003c/li\u003e \u003cli\u003eTurn Left = -2\u003c/li\u003e \u003cli\u003eTurn Slight Left = -1\u003c/li\u003e \u003cli\u003eContinue = 0\u003c/li\u003e \u003cli\u003eTurn Slight Right = 1\u003c/li\u003e \u003cli\u003eTurn Right = 2\u003c/li\u003e \u003cli\u003eTurn Sharp Right = 3\u003c/li\u003e \u003cli\u003eReached via = 5\u003c/li\u003e \u003cli\u003eRoundabout = 6\u003c/li\u003e \u003cli\u003eFinish = 4\u003c/li\u003e\u003c/ul\u003e |\n\n\n## TileJSON\nSignature: `client.tile(profile)`\n\nTileJSON 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.\n\nIn order to get CedarMaps tiles you need to have their specification and then pass these info to your favorite map libarary (Leaflet, OpenLayers, etc.).\n\nFor instance, in our [cedarmaps-web-sdk-raster](https://github.com/cedarstudios/cedarmaps-web-sdk-raster#basic-usage-via-cdn) you use this TileJSON url for displaying map tiles.\n\n| Options | Value | Description |\n|----------------------|--------|-------------------------------------------------------|\n| profile (_required_) | String | Only available option is `cedarmaps.streets` for now. |\n\nSample Response:\n\n```js\n{\n  \"tilejson\": \"2.2.0\",\n  \"name\": \"cedarmaps.streets\",\n  \"version\": \"3.0\",\n  \"description\": \"CedarMaps covers the whole world in general and Iran in details\",\n  \"tiles\": [\n    \"https://api.cedarmaps.com/v1/tiles/cedarmaps.streets/{z}/{x}/{y}.png?access_token=\u003cyour access token\u003e\"\n  ],\n  \"attribution\": \"\u003ca href=\\\"https://www.cedarmaps.com\\\"\u003eCedarMaps\u003c/a\u003e\",\n  \"minzoom\": 0,\n  \"maxzoom\": 17,\n  \"bounds\": [-180, -90, 180, 90]\n}\n```\n\nSample usage:\n\n```js\nclient.tile('cedarmaps.streets', (err, res) =\u003e { console.log(err, res)});\n```\n\n# Issues\nIf you have any questions while implementing Cedar Maps Node.js client, please feel free to open a [new issue](https://github.com/cedarstudios/cedarmaps-nodejs-client/issues).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcedarstudios%2Fcedarmaps-nodejs-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcedarstudios%2Fcedarmaps-nodejs-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcedarstudios%2Fcedarmaps-nodejs-client/lists"}