Call at MapmyIndia
Product release

Personalisation SDK, by MapmyIndia, is India's first O2O engagement tool that can 3X your customer engagement, retention and conversion.


Route API

Routing and displaying driving directions on map, including instructions for navigation, distance to destination, traffic etc. are few of the most important parts of developing a map based application. This REST API calculates driving routes between specified locations including via points based on route type(fastest or shortest), includes delays for traffic congestion , and is capable of handling additional route parameters like: type of roads to avoid, travelling vehicle type etc.


Request Parameters

The input parameters will be supported in the Route / Driving Directions API request are as below:
Note: All Mandatory parameters are marked with a “ * ”.

  1. *licence_key: the REST API licence key allocated to you by signing into our services and registering yourself as a developer (28 Char Alphanumeric).
  2. *Start: the start (departure) point of the route in WGS-84 coordinates, formatted as latitude,longitude.
  3. *destination: the destination of the route in WGS-84 coordinates, formatted as formatted as latitude,longitude.
    e.g.<licence_key>/ route?start=<startLatitude>,<startLongitude> &destination=<destinationLatitude>,<destinationLongitude>

Note: All Parameters defined below are optional parameters and default values will be considered if not sent.

  1. viapoints: the optional list of via-points, pipe ( | ) separated. The complete route will therefore be start – via points in provided order – destination
    e.g. if a single via-point is provided:<licence_key> / route?start=, &destination=, &viapoints={viaLatitude},{viaLongitude}

    e.g. if a multiple via-points are provided:<licence_key>/ route?start=<startLatitude>,<startLongitude> &destination=, &viapoints={viaFirstLatitude},{viaFirstLongitude}|{viaSecondLatitude},{viaSecondLongitude}

    and so on.

    Note: "Maximum of 16 via points can be added." Also, look at the pricing section to know about the pricing and deductions for the use of via points in the API.

  2. rtype: type of route (integer) required for navigation, where values mean:
    - 0 quickest (default)
    - 1 shortest

    e.g. to get quickest route between two places, <licence_key>/ route?start=, &destination=<destinationLatitude>,<destinationLongitude<&rtype=0

  3. vtype: vehicle type (integer), where values mean:

    - 0: passenger
    - 1: taxi (default)

    e.g. if travelling via public transport,<licence_key>/ route?start=, &destination=<destinationLatitude>,&vtype=0

    Note: Select “passenger” if travelling via Public Transport while you can select “taxi” for personal transport.

  4. avoids: The parameter to avoid road types along the route with default value “None (0) or (0000)” Please Note: To get correct combination for your preferred avoidances: Refer to the below table:
    Highways Unpaved roads Ferries Toll roads
    x x x x
    Here x is replaced by Boolean ‘1’ indicating the type of road you wish to avoid. Combine the above 4 bits and convert the resulting 4-bit binary to decimal notation to derive your valid input value for the API. Examples:
    - 1: avoid toll roads (binary: 0001)
    - 2: avoid ferries (binary: 0010)
    - 6: avoid unpaved roads and ferries (binary: 0110)
    - 10: avoid highways and ferries (binary: 1010)
    e.g. to get alternative routes<licence_key>/ route?start=, &destination=,&avoids=10

  5. alternatives: (true or false) : parameter to toggle alternative routes. If “true” is sent, alternative routes will be provided else not.
    e.g. to get alternative routes<licence_key>/ route?start=, &destination=,&with_advices=true

    Please Note: By default, the value is false. So, if the parameter is not sent, no alternative routes will be provided.

  6. with_advices (1 or 0): Advices are turn by turn navigation guidance provided by MapmyIndia routing services (e.g. After 200m take the first exit from the roundabout). To get advices send value 1 (true case) else send 0.

    Please Note: The default value is 0 (i.e. false), so if the parameter is not sent, no advices will be returned.

  7. with_traffic: Accepts boolean 0 or 1 values; The default value if not specified is 1. This parameter is used to get ETA and distance details by taking live traffic flow into account while calculating. Default 1 means, that live traffic is taken into account while calculating ETA and distance for a route.

Response Parameters

The Route / Driving Directions API will respond with multiple objects, depending on the number of pts. input. The following output parameters will be supported in the Route / Driving Directions API response –

  1. responseCode (integer): The response code of the operation.
    The 400 series is for client side (yours) error while 500 series
    for server side (ours) error, 200 for success.
  2. version (string): The version of the API you’re connected to.
  3. Status (integer): 
      a.  Success:
    i) 0 for OK
      b.  Error:
    i) 1 for too few waypoints provided]
    ii)  2 for system error, route calculation failed.
  4. trips (object): A collection of routes that contain an object with the following properties:
  • duration (integer): Duration of the route in seconds.
  • status (integer): Status set by routing engine: 6 means OK, any other number represents specific routing error. (Number)
  • length (integer): Length of the entire trip in meters.
  • pt_start (string): The navigable point from where the route begins.
  • pt_end (string): The navigable point at which the route ends.
  • pts (encoded string): string of WGS-84 longitude-latitude pairs that indicates the path  that needs to be drawn on the map to indicate the computed route.
  • advices (object): An array of advice objects. An advice is the instruction for the end user that often appears at critical points along a route. Each advice object consists of:
    • text (string): Description of the advice.
    • icon_id (integer): The numeric id of the icon that represents current advice icon. For details refer to Appendix C.
    • meters (integer): Distance to the advice location from the start point.
    • seconds (integer): Time to reach to the advice location from the start point.
    • exit_nr (interger): The exit number on roundabout exit, 0 if advice is not on roundabout manoeuvre.
    • pt (object): an object of latitude and longitude of the location of the advice.
      • Lng (double):  longitude of the advice position. 
      • lat (double):  latitude of the advice position

Please Note: If Via Points are provided then each via point is considered as a single trip hence you’ll receive a collection of trips object with 1 item if no via point is added and more if via points are added.

  1. alternatives (trip [ ]): A collection of alternative routes if the alternatives parameter is provided and is set to true else null is returned.
    The Data type is the same as that of the trip object
    Please Note: In case Via-Points are provided, no alternative routes will be returned.

Please Note: The data types defined a (encoded string) you will have to decode it using the polyline points decoder (code easily available online) that’ll provide you with a string of dollar separated “Latitude$Longitude” and Pipeline separated “Latitude$Longitude| Latitude$Longitude” values which you can convert to a collection of latitudes and longitudes using string  operations


The Route / Driving Directions API must respond within 100 ms under all circumstances on a stable internet connection although on an unstable one, response times may vary.

Also, with each addition of a via point, the response times may vary depending upon the complexity of the generated route.

Transaction Information

  1. The pair of start and destination are required for 1 valid transaction of this API. 
  2. via point costs as an additional transaction.
    e.g.  If there are three via points (A,B,C) and the Start Point is X while the Destination is Y then, there will be 4 transactions for that GET request with 3 via points (namely: X-A, A-B, B-C, C-D and then D-Y).
    Credits will be accordingly deducted. 

Use Cases

  1. To get driving navigations for one location to another. 
  2. To calculate distance and time to reach a destination. In this case, it is recommended that you use Driving Distance Matrix API




{  "responseCode": 200,  "version": "130.10",  "results": {  "alternatives": [  {  "advices": [  {  "exit_nr": 0,  "icon_id": 50,  "meters": 0,  "pt": {  "lat": 28.110999536368,  "lng": 77.110999971628  },  "seconds": 0,  "text": "Head north."  },  {  "exit_nr": 0,  "icon_id": 7,  "meters": 1972,  "pt": {  "lat": 28.120864493862,  "lng": 77.091525793076  },  "seconds": 1182,  "text": "Continue straight."  },  {  "exit_nr": 0,  "icon_id": 3,  "meters": 6033,  "pt": {  "lat": 28.113701252852,  "lng": 77.051153182983  },  "seconds": 1689,  "text": "Turn right at Salamba Main Road."  },  {  "exit_nr": 0,  "icon_id": 18,  "meters": 7681,  "pt": {  "lat": 28.121148364097,  "lng": 77.042280435562  },  "seconds": 1991,  "text": "At the next intersection make a sharp right turn onto SH 13."  },  {  "exit_nr": 0,  "icon_id": 3,  "meters": 23135,  "pt": {  "lat": 28.241791270843,  "lng": 77.070894241333  },  "seconds": 4004,  "text": "Turn right at NH 71B."  },  {  "exit_nr": 0,  "icon_id": 0,  "meters": 37149,  "pt": {  "lat": 28.204554687803,  "lng": 77.206506729126  },  "seconds": 5281,  "text": "Turn left."  },  {  "exit_nr": 0,  "icon_id": 72,  "meters": 38994,  "pt": {  "lat": 28.219999425573,  "lng": 77.219999581575  },  "seconds": 6388,  "text": "You will arrive at your intermediate destination."  }  ],  "duration": 6436,  "length": 38994,  "pts": "wrxrt@mfgarCoE~@uVn\qi@fg@yMtGin@lP{kAtGeM`GqO`Oup@tlDolAbwF{GvOql@fi@_Yza@e{BrsItSfdB`jBrlRdqA~fMbgAfgKllBjzIbP`dAdMbpHxWteFqO``Ae]bjAoE?up@owAcSkHap@bY}{@nVcP`MikAp~CcPx[z~@~s@uxDdnEpBeqCcCe]oRwhAwgAepEgWux@ihAkvB_sAskBoiAesCuFoXyMayBuF{]s`AikDew@clAujAskBuSwImXkDas@uActAtAgd@aEqi@mLum@yYo|@go@sYmLqsAmNckCea@saDoZalOux@}xHwQmsJo^uiF{]ouFyYoy@`EihA`MgbCxWqv@aIoE~@k`DuGac@aKahDclAcz@wO{_Jst@gd@Uc]jBeZtGc]vQ{}DvcC_qCrgBwCtA{|BbpAsp@lR{wEleAstBze@cw@lRcsE`dAkkFloAilBpb@srD~y@k`Cfi@oEh@gTuCqs@yUw}E{`BwhB}m@mHuCcj@ySmKaGe{Auz@ghAo^mHuC}wDmmAg|Bis@q_Kg}Cs{B}q@wMaEcPuGiD_Ad@kDpBySnEo\pBaM`Fea@nEq{Ad@qb@d@oZv@cSbC}q@nE{c@xJiu@rV}jBxq@}_DvCuCpzAooLjXorClH_z@bCcWhDe_@P_ChDo^bCcY|AmNpBoV`Iiy@pBoVbCyUbCySh^g}CliAkcHdkAi{GblDa`Sje@yoChDySvM_v@jr@a{BfTsv@pLqh@ny@koDn_@gbBdaAifFjoAqgIppAghIzk@avDje@icD|Q}bBxsDa|KtbD}eKvP}o@`kCk~IvqAc|DlHcW`S}o@|k@w}BpBkH~r@wcCdZ{`Bjh@_oB~`CsfKvg@wvDlr@w~DbPevAwCsmBpLaxDpLowApi@m`Cn_@ghBkh@yWsVmRmpBewCgwEslKcCmNm~D_{I"  },  {  "advices": [  {  "exit_nr": 0,  "icon_id": 50,  "meters": 0,  "pt": {  "lat": 28.110999536368,  "lng": 77.110999971628  },  "seconds": 0,  "text": "Head north."  },  {  "exit_nr": 0,  "icon_id": 3,  "meters": 1972,  "pt": {  "lat": 28.120864493862,  "lng": 77.091525793076  },  "seconds": 1182,  "text": "Turn right."  },  {  "exit_nr": 0,  "icon_id": 0,  "meters": 24641,  "pt": {  "lat": 28.140629528191,  "lng": 77.318365573883  },  "seconds": 4079,  "text": "Turn left."  },  {  "exit_nr": 0,  "icon_id": 13,  "meters": 24841,  "pt": {  "lat": 28.142218898658,  "lng": 77.319320440292  },  "seconds": 4103,  "text": "At the end of the road turn left onto NH 71B."  },  {  "exit_nr": 0,  "icon_id": 3,  "meters": 38068,  "pt": {  "lat": 28.204554687803,  "lng": 77.206506729126  },  "seconds": 5310,  "text": "Turn right."  },  {  "exit_nr": 0,  "icon_id": 8,  "meters": 39913,  "pt": {  "lat": 28.219999425573,  "lng": 77.219999581575  },  "seconds": 6417,  "text": "You will arrive at your destination."  }  ],  "duration": 6450,  "length": 39913,  "pts": "wrxrt@mfgarCoE~@uVn\qi@fg@yMtGin@lP{kAtGeM`GqO`Oup@tlDolAbwF{GvOql@fi@_Yza@e{BrsIkNo^y_E}qG{{AavDwj@wbLiQkuDk[i{Ggq@a|KghBi|Wme@keHsf@ggK}DcYyJwQw]o^swBorCkAaIcCwMza@kjXv@qd@`VqgPQopJsLckCgt@kiHql@_aFoEsl@yMqhGyJ}vEsVwdSQq_B{TylScFoyAg{AgaKvCevA|A{c@|A{_@jh@uoMjAaO|k@a}Bpy@sbDQowHuSumMyZ}iK{d@wtOqOqgIeZyrHcFqaBap@gfTmKmaE{Gq~Co_@ikKyg@yuQoU}bBwCoX}D{a@gGgm@cFqf@iDe[iDe[cSkzB{GaEgJuEgnA}m@gWd_@cPlTsIlLsf@rn@ew@tz@yJvKol@|o@gWxY}^za@{a@fi@kh@tx@}NbWum@`fAac@hu@qi@j{@cgAbpAa}@d|Aob@~u@i_CpjGmyAp|Csf@vjAqcAzqCsLbYkNbYqOxY}A`EwPnXyuBxbEyJbSaIlPugAf}C}A|q@{TbnAku@bkC{hA`{Bgd@xnAkeAzuCyd@dzAuwHd}JgjFh{G_rEbyF_|FphGgmEdgGqpAbeCoRt`Ac]bjAw~A`qFqi@dzAocBtlDyrB`jHwt@tnDwt@zrE{uAb_GaVfm@u`@vbA}vBvvDy|CnfNgbBlhJaId]kh@yWsVmRmpBewCgwEslKcCmNm~D_{I"  }  ],  "trips": [  {  "advices": [  {  "exit_nr": 0,  "icon_id": 50,  "meters": 0,  "pt": {  "lat": 28.110999536368,  "lng": 77.110999971628  },  "seconds": 0,  "text": "Head north."  },  {  "exit_nr": 0,  "icon_id": 3,  "meters": 1972,  "pt": {  "lat": 28.120864493862,  "lng": 77.091525793076  },  "seconds": 1182,  "text": "Turn right."  },  {  "exit_nr": 0,  "icon_id": 0,  "meters": 11287,  "pt": {  "lat": 28.133798750963,  "lng": 77.183225154877  },  "seconds": 2389,  "text": "Turn left."  },  {  "exit_nr": 0,  "icon_id": 0,  "meters": 21023,  "pt": {  "lat": 28.190881944989,  "lng": 77.24319934845  },  "seconds": 4434,  "text": "Turn left at NH 71B."  },  {  "exit_nr": 0,  "icon_id": 3,  "meters": 24943,  "pt": {  "lat": 28.204554687803,  "lng": 77.206506729126  },  "seconds": 4795,  "text": "Turn right."  },  {  "exit_nr": 0,  "icon_id": 8,  "meters": 26788,  "pt": {  "lat": 28.219999425573,  "lng": 77.219999581575  },  "seconds": 5902,  "text": "You will arrive at your destination."  }  ],  "duration": 5913,  "length": 26788,  "pts": "wrxrt@mfgarCoE~@uVn\qi@fg@yMtGin@lP{kAtGeM`GqO`Oup@tlDolAbwF{GvOql@fi@_Yza@e{BrsIkNo^y_E}qG{{AavDwj@wbLiQkuDk[i{Ggq@a|KghBi|Wme@keHsf@ggK}DcYyJwQw]o^swBorCkAaIcCwMza@kjXv@qd@`VqgPQopJsLckCgt@kiHamAhw@sYsl@wlEa~@gnAezAq\{_@ubEqwEofB{zAghBkcAozCicDac@}k@ww@q_BqqD_AsL?kN?igNuAszImN{GaMobGggKk`DofGww@{c@sp@ux@mlAseBwdAa_Cmb@etA_wBylL{uAc_GerCiiKwj@{zAsL{_@kyBweJu`@moAaFm`CiQaEocBuAeg@uEocBtlDyrB`jHwt@tnDwt@zrE{uAb_GaVfm@u`@vbA}vBvvDy|CnfNgbBlhJaId]kh@yWsVmRmpBewCgwEslKcCmNm~D_{I"  }  ]  }  }