Travel Time & Distance - Distance Matrix API

The Distance Matrix API returns a top-level status field with information about the request in general, as well as a status field for each element field with ... Products Solutions Resources Pricing Signin Getafreetrial Products Solutions Signin Resources Pricing Contactus Contactus Developerguides Developerguides TheDistanceMatrixAPI TheDistanceMatrixAPI TheGeocodingAPI TheGeocodingAPI TheAsynchronousDistanceMatrixAPI(Beta) TheAsynchronousDistanceMatrixAPI(Beta) DistanceMatrixAPIguide GeocodingAPIguide DistanceMatrixAPIguide GeocodingAPIguide DMAPIapplicationguide DMAPIapplicationguide Fooddelivery Taxiservices Fooddelivery Taxiservices Courierservices Logistics&Transportation Courierservices Logistics&Transportation DistanceMatrixpricing DistanceMatrixpricing Geocodingpricing Geocodingpricing Ournews Ournews Usefulguides Usefulguides Casestudies Casestudies Products TheDistanceMatrixAPI TheAsynchronousDMAPI(Beta) TheGeocodingAPI Developerguides DistanceMatrixAPIguide GeocodingAPIguide DMAPIapplicationguide Solutions Fooddelivery Taxiservices Courierservices Logistics&Transportation Pricing DistanceMatrixpricing Geocodingpricing Resources Ournews Usefulguides Casestudies Contactus Signin Getafreetrial DistanceMatrixAPI|TravelTime&Distance GuidelinesforDevelopers Introduction Introduction Requests Requests Responses Responses Introduction Beforeyoubegin Beforeyoubegin WhatcanyoudowiththeDistanceMatrixAPI? WhatcanyoudowiththeDistanceMatrixAPI? WhyuseDistanceMatrixAPI? WhyuseDistanceMatrixAPI? HowtouseDistanceMatrixAPI HowtouseDistanceMatrixAPI Usagelimits Usagelimits Beforeyoubegin ItisanHTTPAPIservicethatisdesignedtocalculateallpossiblecombinationsbetweenthestartingpointandthedestinationandallowsyoutoconsidertrafficcongestionandaspecificmodeoftransport.ThistraveltimeAPIisavailableanywhereintheworldandensuresasimilarlevelofaccuracyandresponsewiththebestanalogslikethegoogledistancematrixAPI.InthisDistanceMatrixAPIdocumentation,youcanfindanintroductionfortheproductusingandreferencematerialontheavailableparameters. WhatcanyoudowiththeDistanceMatrixAPI? Thisproductensuresdeveloperswithacalculationoftraveltimeanddistancebetweensomepoints.So,differenttypesofdelivery&courierserviceslikefood,goods,andmedicinedeliveryhavesignificantbenefitsfromtheiruse.Besides,youcanuseourAPIinrouteplanning,logistics,andtransportation,aswellasinsoftwaredevelopment,realestate,andhomeandbusinessservices.Inparticular,theproductiscriticallyhelpfulfortaxiapplications.Itallowscalculatingthecardeliverytimewhilerespectingtrafficjamsandcongestion.Tochoosetheshortestrouteofthefooddeliveryservicefromcafesandrestaurants,ourtraveltimeAPIcalculatesthedeliverytimefromeachrestauranttothecustomer'saddressconsideringtheroadcongestion. WhyuseDistanceMatrixAPI? Youcanuseourproducttofindthedestinationpointclosesttotheoriginpointorforanyotherpurpose.TheAPIwillalwaysreturnadurationandadistanceonthefastestrouteforeachelement.Inturn,eachelementisanorigin-destinationpair.Thissolutionworksworldwideandisavailablefordriving,walking,bicycling,andtransittravelmodes.Ifreal-timetrafficdoesnotaffectyourbusinesssignificantly,youcansavetimeandincreasetheproduct'sperformancebyusingitsversionwithouttrafficmonitoring.Forlargecalculatingvolume,youcanconsiderourAsynchronousDistanceMatrixAPI. HowtouseDistanceMatrixAPI Yougiveinputdata(addressesorcoordinates)forwhichyouwanttomakeanestimation.YouwillreceiveananswerinJSONformat,andtheresponsewillcontaininformationaboutthedurationofeachconstructedroutesection.Thecalculatedtraveltimeforaroutesectionalwaysaccountsforthecurrenttrafficconditionsandthetrafficforecast.Forexample,therearethreestartinglocationsA,B,andC,andthreedestinationlocationsE,B,andD.TheDistanceAPIreturnsthematrixofdurationsinsecondsanddistancesinmetersbetweenthelocations.Itdoesnotreturnroutegeometries. ↓origins\destinations E B D A AtoE AtoB AtoD B BtoE BtoB=0 BtoD C CtoE CtoB CtoD Thetimeanddistancebetweenpointsmaynotbesymmetricsincetheroutesmaydifferbydirectionduetoone-waystreetsorturnrestrictions.Forexample,AtoBmayhaveadifferentdurationthanBtoA.ThefollowingsectionsensureyouwithmoredetailedinformationbasedonDistanceMatrixAPIexamples. ↓ DistanceMatrixRequests RequestParameters RequestParameters RequiredParameters RequiredParameters OptionalParameters OptionalParameters TrafficInformation TrafficInformation Restrictions Restrictions UnitSystems UnitSystems TravelModes TravelModes RequestParameters TheDistanceMatrixAPIrequestwascreatedspecificallytobesimilartotheGoogleDistanceMatrixAPIrequestformat.YoucangetmoreinformationontheMigratetoDistanceMatrix.aiAPIpage. ADistanceMatrixAPIrequesttakesthefollowingform: GET: https://api.distancematrix.ai/maps/api/distancematrix/json?origins=&destinations=&key= ADistanceMatrixAPIrequestexample: GET: https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&key= RequestParameters TheDistanceMatrixAPIrequestwascreatedspecificallytobesimilartotheGoogleDistanceMatrixAPIrequestformat.YoucangetmoreinformationontheMigratetoDistanceMatrix.aiAPIpage. ADistanceMatrixAPIrequesttakesthefollowingform: GET: https://api.distancematrix.ai/maps/api/distancematrix/json?origins=&destinations=&key= ADistanceMatrixAPIrequestexample: GET: https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&key= RequiredParameters origins—astartingpointforcalculatingtraveldistanceandtime.Youcansupplyoneormorelocationsseparatedbythepipecharacter(|)intheformofanaddressorlatitude/longitudecoordinates: 1.Ifyoupassanaddress,theservicegeocodesthestringandconvertsittoalatitude/longitudecoordinatetocalculatethedistance.ThiscoordinatemaybedifferentfromthatreturnedbytheGeocodingAPI,forexample,abuildingentranceratherthanitscenter. Showexample Hideexample Showexample Examplerequestwithaddresses: GET: https://api.distancematrix.ai/maps/api/distancematrix/json?origins=WestminsterAbbey,20DeansYd,Westminster,LondonSW1P3PA,UnitedKingdom&destinations=StJohn'sChurch,NorthEndRd,Fulham,LondonSW61PB,UnitedKingdom&key= Response BODY {\t"destination_addresses":[ "StJohn'sChurch,NorthEndRd,Fulham,LondonSW61PB,UnitedKingdom"],"origin_addresses":["WestminsterAbbey,20DeansYd,Westminster,LondonSW1P3PA,UnitedKingdom"],"rows":[{"elements":[{"distance":{"text":"6.5km","value":6477},"duration":{"text":"21min","value":1287},"status":"OK"}]}],"status":"OK"} { "destination_addresses":[ "StJohn'sChurch,NorthEndRd,Fulham,LondonSW61PB,UnitedKingdom" ], "origin_addresses":[ "WestminsterAbbey,20DeansYd,Westminster,LondonSW1P3PA,UnitedKingdom" ], "rows":[ { "elements":[ { "distance":{ "text":"6.5km","value":6477}, "duration":{ "text":"21min","value":1287}, "status":"OK"} ] } ], "status":"OK"} 2.Ifyoupasslatitude/longitudecoordinates,theyareusedunchangedtocalculatedistance.Ensurethatnospaceexistsbetweenthelatitudeandlongitudevalues. Showexample Hideexample Showexample Examplerequestwithcoordinates: GET: https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&key= Response BODY {"destination_addresses":["WestminsterAbbey,Westminster,LondonSW1P3PA,UK"],"origin_addresses":["Chapel,Fulham,LondonSW61BA,UK"],"rows":[{"elements":[{"distance":{"text":"7.6km","value":7561},"duration":{"text":"22min","value":1303},"status":"OK"}]}],"status":"OK"} { "destination_addresses":[ "StJohn'sChurch,NorthEndRd,Fulham,LondonSW61PB,UnitedKingdom" ], "origin_addresses":[ "WestminsterAbbey,20DeansYd,Westminster,LondonSW1P3PA,UnitedKingdom" ], "rows":[ { "elements":[ { "distance":{ "text":"6.5km","value":6477}, "duration":{ "text":"21min","value":1287}, "status":"OK"} ] } ], "status":"OK"} destinations—oneormorelocationstouseasthefinaldestinationforcalculatingtraveldistanceandtime.Theoptionsforthedestinationparameterarethesameasfortheoriginalparameter,asdescribedabove. key—theAPIkeyofyourapplication OptionalParameters mode(defaultstodriving)—specifiesthemodeoftransporttousewhencalculatingdistance.ValidvaluesandotherrequestdetailsarespecifiedintheTravelModessectionofthisdocument. language—alanguagethatisusedtoreturnresults. Seethelistofsupportedlanguages. Iflanguageisnotsupplied,theAPIattemptstousethepreferredlanguageasspecifiedintheAccept-Languageheader,orthenativelanguageofthedomainfromwhichtherequestissent. TheAPIdoesitsbesttoprovideastreetaddressthatisreadableforboththeuserandlocals.Toachievethatgoal,itreturnsstreetaddressesinthelocallanguage,transliteratedtoascriptreadablebytheuserifnecessary,observingthepreferredlanguage.Allotheraddressesarereturnedinthepreferredlanguage.Addresscomponentsareallreturnedinthesamelanguage,whichischosenfromthefirstcomponent. Ifanameisnotavailableinthepreferredlanguage,theAPIusestheclosestmatch. ThepreferredlanguagehasasmallinfluenceonthesetofresultsthattheAPIchoosestoreturn,andtheorderinwhichtheyarereturned.Thegeocoderinterpretsabbreviationsdifferentlydependingonlanguage,suchastheabbreviationsforstreettypes,orsynonymsthatmaybevalidinonelanguagebutnotinanother.Forexample,utcaandtéraresynonymsforstreetinHungarian. Showlanguages Hidelanguages Showlanguages LanguageCode Language LanguageCode Language af Afrikaans ja sq Albanian kn Kannada am Amharic kk Kazakh Japanese ar Arabic km hy Armenian ko Korean az Azerbaijani ky Kyrgyz Khmer eu Basque lo be Belarusian lv Latvian bn Bengali lt Lithuanian Lao bs Bosnian mk bg Bulgarian ms Malay my Burmese ml Malayalam Macedonian ca Catalan mr zh Chinese mn Mongolian zh-CN Chinese(Simplified) ne Nepali Marathi zh-HK Chinese(HongKong) no zh-TW Chinese(Traditional) pl Polish hr Croatian pt Portuguese Norwegian cs Czech pt-BR da Danish pt-PT Portuguese(Portugal) nl Dutch pa Punjabi Portuguese(Brazil) en English ro en-AU English(Australian) ru Russian en-GB English(GreatBritain) sr Serbian Romanian et Estonian si Sinhalese fa Farsi sk Slovak fi Finnish sl fil Filipino es Spanish fr French es-419 Spanish(LatinAmerica) Slovenian fr-CA French(Canada) sw gl Galician sv Swedish ka Georgian ta Tamil Swahili de German te el Greek th Thai gu Gujarati tr Turkish Telugu iw Hebrew uk hi Hindi ur Urdu hu Hungarian uz Uzbek Ukrainian is Icelandic vi id Indonesian zu Zulu it Italian Vietnamese avoid—introducesrestrictionstotheroute.ValidvaluesarespecifiedintheRestrictionssectionofthisdocument.Onlyonerestrictioncanbespecified. units—specifiestheunitsystemtousewhenexpressingdistanceastext.SeetheUnitSystemssectionofthisdocumentformoreinformation. arrival_time—specifiesthedesiredtimeofarrivalfortransitrequests,insecondssincemidnight,January1,1970,UTC.Youcanspecifyeitherdeparture_timeorarrival_time,butnotboth.Notethatarrival_timemustbespecifiedasaninteger Showexample Hideexample Showexample Requestexamplewitharrival_time: GET: https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.507033,-0.1277161&destinations=52.486243,-1.890401&arrival_time=now&transit_mode=bus&mode=transit&key= Response BODY {"destination_addresses":["BirminghamB47DL,UK"],"origin_addresses":["Whitehall,Westminster,London,UK"],"rows":[{"elements":[{"distance":{"text":"202.4km","value":202400},"duration":{"text":"2h20min","value":8421},"status":"OK"}]}],"status":"OK"} { "destination_addresses":[ "BirminghamB47DL,UK"], "origin_addresses":[ "Whitehall,Westminster,London,UK"], "rows":[ { "elements":[ { "distance":{ "text":"202.4km","value":202400}, "duration":{ "text":"2h20min","value":8421}, "status":"OK"} ] } ], "status":"OK" } departure_time—adesiredtimeofthedeparture.Youcanspecifythetimeasanintegerinsecondssincemidnight,January1,1970,UTC.Alternatively,youcanspecifyavalueofnow,whichsetsthedeparturetimetothecurrenttime(correcttothenearestsecond).Thedeparture_timemustbesettothecurrenttimeorsometimeinthefuture.Itcannotbeinthepast.Resultsforagivenrequestmayvaryovertimeduetothechangesintheroadnetwork,updatedaveragetrafficconditions,andthedistributednatureoftheservice.Resultsmayalsovarybetweennearly-equivalentroutesatanytimeorfrequency.Thedeparturetimemaybespecifiedintwocases: Forrequestswherethetravelmodeistransit:Youcanoptionallyspecifyoneofdeparture_timeorarrival_time.Ifneithertimeisspecified,thedeparture_timedefaultstonow(thatis,thedeparturetimedefaultstothecurrenttime). Forrequestswherethetravelmodeisdriving:Youcanspecifythedeparture_timetoreceivearouteandtripduration(responsefield:duration_in_traffic)thattaketrafficconditionsintoaccount.Thedeparture_timemustbesettothecurrenttimeorsometimeinthefuture.Itcannotbeinthepast. *Note:Ifdeparturetimeisnotspecified,choiceofrouteanddurationarebasedonroadnetworkandaveragetime-independenttrafficconditions.Resultsforagivenrequestmayvaryovertimeduetochangesintheroadnetwork,updatedaveragetrafficconditions,andthedistributednatureoftheservice.Resultsmayalsovarybetweennearly-equivalentroutesatanytimeorfrequency. Showexample Hideexample Showexample Examplerequestwithdeparture_time: GET: https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.507033,-0.1277161&destinations=52.486243,-1.890401&departure_time=now&key= Response BODY {"destination_addresses":["BirminghamB47DL,UK"],"origin_addresses":["Whitehall,Westminster,London,UK"],"rows":[{"elements":[{"distance":{"text":"202.4km","value":202399},"duration":{"text":"2h18min","value":8294},"duration_in_traffic":{"text":"2hour0mins","value":7200},"status":"OK"}]}],"status":"OK"} { "destination_addresses":[ "BirminghamB47DL,UK"], "origin_addresses":[ "Whitehall,Westminster,London,UK"], "rows":[ { "elements":[ { "distance":{ "text":"202.4km","value":202400}, "duration":{ "text":"2h20min","value":8421}, "status":"OK"} ] } ], "status":"OK" } traffic_model(defaultstobest_guess)—specifiestheassumptionstousewhencalculatingtimeintraffic.Thissettingaffectsthevaluereturnedintheduration_in_trafficfieldintheresponse,whichcontainsthepredictedtimeintrafficbasedonhistoricalaverages.Thetraffic_modelparametermayonlybespecifiedforrequestswherethetravelmodeisdriving,andwheretherequestincludesadeparture_time.Theavailablevaluesforthisparameterare: best_guess(default)indicatesthatthereturnedduration_in_trafficshouldbethebestestimateoftraveltimegivenwhatisknownaboutbothhistoricaltrafficconditionsandlivetraffic.Livetrafficbecomesmoreimportantthecloserthedeparture_timeistonow. pessimisticindicatesthatthereturnedduration_in_trafficshouldbelongerthantheactualtraveltimeonmostdays,thoughoccasionaldayswithparticularlybadtrafficconditionsmayexceedthisvalue. optimisticindicatesthatthereturnedduration_in_trafficshouldbeshorterthantheactualtraveltimeonmostdays,thoughoccasionaldayswithparticularlygoodtrafficconditionsmaybefasterthanthisvalue. Showexample Hideexample Showexample Examplerequestwithtraffic_model: GET: https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.507033,-0.1277161&destinations=52.486243,-1.890401&traffic_model=pessimistic&departure_time=now&key= Response BODY {"destination_addresses":["BirminghamB47DL,UK"],"origin_addresses":["Whitehall,Westminster,London,UK"],"rows":[{"elements":[{"distance":{"text":"202.4km","value":202400},"duration":{"text":"2h20min","value":8421},"duration_in_traffic":{"text":"3hour0mins","value":10800},"status":"OK"}]}],"status":"OK"} { "destination_addresses":[ "BirminghamB47DL,UK"], "origin_addresses":[ "Whitehall,Westminster,London,UK"], "rows":[ { "elements":[ { "distance":{ "text":"202.4km","value":202400}, "duration":{ "text":"2h20min","value":8421}, "duration_in_traffic":{ "text":"3hour0mins","value":10800}, "status":"OK"} ] } ], "status":"OK" } transit_mode—specifiesoneormorepreferredmodesoftransit.Thisparametermayonlybespecifiedforrequestswherethemodeistransit.Theparametersupportsthefollowingarguments: busindicatesthatthecalculatedrouteshouldprefertravelbybus. subwayindicatesthatthecalculatedrouteshouldprefertravelbysubway. trainindicatesthatthecalculatedrouteshouldprefertravelbytrain. subwayindicatesthatthecalculatedrouteshouldprefertravelbysubway. railindicatesthatthecalculatedrouteshouldprefertravelbytrain,tram,lightrail,andsubway.Thisisequivalenttotransit_mode=train|tram|subway. Showexample Hideexample Showexample Requestexamplewitharrival_time: GET: https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.507033,-0.1277161&destinations=52.486243,-1.890401&transit_mode=bus|train|tram|subway&mode=transit&departure_time=now&key= Response BODY {"destination_addresses":["BirminghamB47DL,UK"],"origin_addresses":["Whitehall,Westminster,London,UK"],"rows":[{"elements":[{"distance":{"text":"202.4km","value":202399},"duration":{"text":"2h20min","value":8421},"status":"OK"}]}],"status":"OK"} { "destination_addresses":[ "BirminghamB47DL,UK"], "origin_addresses":[ "Whitehall,Westminster,London,UK"], "rows":[ { "elements":[ { "distance":{ "text":"202.4km","value":202400}, "duration":{ "text":"2h20min","value":8421}, "status":"OK"} ] } ], "status":"OK" } TravelModes driving(default)indicatesdistancecalculationusingtheroadnetwork. walkingrequestsdistancecalculationforwalkingviapedestrianpaths&sidewalks(whereavailable). Forthecalculationofdistances,youmayspecifythetransportationmodetouse.Bydefault,distancesarecalculatedforthedrivingmode.Thefollowingtravelmodesaresupported: bicyclingrequestsdistancecalculationforbicyclingviabicyclepaths&preferredstreets(whereavailable). transitrequestsdistancecalculationviapublictransitroutes(whereavailable).Ifyousetthemodetotransityouneedspecifyeitheradeparture_timeoranarrival_time.Ifneithertimeisspecified,thedeparture_timedefaultstonow(thatis,thedeparturetimedefaultstothecurrenttime).Youneedalsoincludeatransit_mode. Showexample Hideexample Showexample Examplerequestwithtravelmodes: GET: https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&mode=walking&departure_time=now&key= Response BODY {"destination_addresses":["WestminsterAbbey,Westminster,LondonSW1P3PA,UK"],"origin_addresses":["Chapel,Fulham,LondonSW61BA,UK"],"rows":[{"elements":[{"distance":{"text":"6.2km","value":6187},"duration":{"text":"1h19min","value":4723},"status":"OK"}]}],"status":"OK"} { "destination_addresses":[ "WestminsterAbbey,Westminster,LondonSW1P3PA,UK"], "origin_addresses":[ "Chapel,Fulham,LondonSW61BA,UK"], "rows":[ { "elements":[ { "distance":{ "text":"6.2km","value":6187}, "duration":{ "text":"1h19min","value":4723}, "status":"OK"} ] } ], "status":"OK" } TrafficInformation Thetravelmodeparameterisdriving,oritisnotspecified(drivingisthedefaulttravelmode). Therequestincludesavaliddeparture_timeparameter.Thedeparture_timecanbesettothecurrenttimeorsomeothertime. Trafficinformationisusedwhenallthefollowingapply(thesearetheconditionsrequiredtoreceivetheduration_in_trafficfieldintheDistanceMatrixresponse): Optionally,youcanincludethetraffic_modelparameterinyourrequesttospecifytheassumptionstousewhencalculatingtimeintraffic. Showexample Hideexample Showexample Examplerequestwithtrafficinformation: GET: https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&mode=driving&departure_time=now&key= Response BODY {"destination_addresses":["WestminsterAbbey,Westminster,LondonSW1P3PA,UK"],"origin_addresses":["Chapel,Fulham,LondonSW61BA,UK"],"rows":[{"elements":[{"distance":{"text":"7.6km","value":7561},"duration":{"text":"20min","value":1205},"duration_in_traffic":{"text":"16mins","value":960},"status":"OK"}]}],"status":"OK"} { "destination_addresses":[ "WestminsterAbbey,Westminster,LondonSW1P3PA,UK"], "origin_addresses":[ "Chapel,Fulham,LondonSW61BA,UK"], "rows":[ { "elements":[ { "distance":{ "text":"7.6km","value":7561}, "duration":{ "text":"20min","value":1205}, "duration_in_traffic":{ "text":"16min","value":960}, "status":"OK"} ] } ], "status":"OK" } Restrictions avoid=tolls avoid=highways Distancesmaybecalculatedthatadheretocertainrestrictions.Restrictionsareindicatedbytheuseoftheavoidparameterandanargumenttothatparameterindicatingtherestrictiontoavoid.Thefollowingrestrictionsaresupported: avoid=ferries avoid=indoor *Note:theadditionofrestrictionsdoesnotprecluderoutesthatincludetherestrictedfeature;itsimplybiasestheresulttomorefavorableroutes. Showexample Hideexample Showexample Examplerequestwithrestrictions: GET: https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&mode=driving&departure_time=now&avoid=ferries&key= Response BODY {"destination_addresses":["WestminsterAbbey,Westminster,LondonSW1P3PA,UK"],"origin_addresses":["Chapel,Fulham,LondonSW61BA,UK"],"rows":[{"elements":[{"distance":{"text":"7.6km","value":7561},"duration":{"text":"20min","value":1205},"duration_in_traffic":{"text":"18mins","value":1080},"status":"OK"}]}],"status":"OK"} { "destination_addresses":[ "WestminsterAbbey,Westminster,LondonSW1P3PA,UK"], "origin_addresses":[ "Chapel,Fulham,LondonSW61BA,UK"], "rows":[ { "elements":[ { "distance":{ "text":"7.6km","value":7561}, "duration":{ "text":"20min","value":1205}, "duration_in_traffic":{ "text":"18min","value":1080}, "status":"OK"} ] } ], "status":"OK" } UnitSystems units=metric(default)returnsdistancesinkilometersandmeters. units=imperialreturnsdistancesinmilesandfeet. DistanceMatrixresultscontaintextwithindistancefieldstoindicatethedistanceofthecalculatedroute.Theunitsystemtousecanbespecified: Showexample Hideexample Showexample Examplerequestwithunitsystem: GET: https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&departure_time=now&units=imperial&key= Response BODY {"destination_addresses":["WestminsterAbbey,Westminster,LondonSW1P3PA,UK"],"origin_addresses":["Chapel,Fulham,LondonSW61BA,UK"],"rows":[{"elements":[{"distance":{"text":"4.7miles","value":7561},"duration":{"text":"20min","value":1205},"duration_in_traffic":{"text":"18mins","value":1080},"status":"OK"}]}],"status":"OK"} { "destination_addresses":[ "WestminsterAbbey,Westminster,LondonSW1P3PA,UK"], "origin_addresses":[ "Chapel,Fulham,LondonSW61BA,UK"], "rows":[ { "elements":[ { "distance":{ "text":"4.7km","value":7561}, "duration":{ "text":"20min","value":1205}, "duration_in_traffic":{ "text":"18min","value":1080}, "status":"OK"} ] } ], "status":"OK" } *Note:thisunitsystemsettingonlyaffectsthetextdisplayedwithindistancefields.Thedistancefieldsalsocontainvalueswhicharealwaysexpressedinmeters. DistanceMatrixResponses Responseexample Responseexample DistanceMatrixResponseElements DistanceMatrixResponseElements StatusCodes StatusCodes Element-levelStatusCodes Element-levelStatusCodes ErrorMessages ErrorMessages Rows Rows Top-levelStatusCodes Top-levelStatusCodes Elements Elements Responseexample Theresponsecontainsanarrayofrowsobjects,eachrowcontainingoneoriginpairedwitheachdestination.Eachelementoftheobjectinthearraycontainsthepropertiesofasingleroutevariant.Forthedetaileddescriptionofelements,seethesectionDistanceMatrixResponseElements. Response BODY {"destination_addresses":["WestminsterAbbey,Westminster,LondonSW1P3PA,UK"],"origin_addresses":["Chapel,Fulham,LondonSW61BA,UK"],"rows":[{"elements":[{"distance":{"text":"4.7miles","value":7565},"duration":{"text":"22min","value":1306},"status":"OK"}]}],"status":"OK"} { "destination_addresses":[ "WestminsterAbbey,Westminster,LondonSW1P3PA,UK"], "origin_addresses":[ "Chapel,Fulham,LondonSW61BA,UK"], "rows":[ { "elements":[ { "distance":{ "text":"4.7km","value":7565}, "duration":{ "text":"22min","value":1306}, "status":"OK"} ] } ], "status":"OK" } DistanceMatrixResponseElements statuscontainsmetadataontherequest.SeeStatusCodesbelow. origin_addressescontainanarrayofaddressesasreturnedbytheAPIfromyouroriginalrequest.Theseareformattedbythegeocoderandlocalizedaccordingtothelanguageparameterpassedwiththerequest. DistanceMatrixresponsescontainthefollowingrootelements destination_addressescontainanarrayofaddressesreturnedbytheAPIfromyourinitialrequest.Aswithorigin_addresses,thesearelocalizedifappropriate. rowscontainanarrayofelements,whichinturncontainstatus,duration,anddistanceelement. StatusCodes Thestatusfieldswithintheresponseobjectcontainthestatusoftherequestandmaycontainusefuldebugginginformation.TheDistanceMatrixAPIreturnsatop-levelstatusfieldwithinformationabouttherequestingeneral,aswellasastatusfieldforeachelementfieldwithinformationaboutthatparticularorigin-destinationpairing. Top-levelStatusCodes OKindicatestheresponseandcontainsavalidresult. INVALID_REQUESTindicatesthattheprovidedrequestwasinvalid. TheAPIkeyismissingorinvalid. Billinghasnotbeenenabledonyouraccount. Aself-imposedusagecaphasbeenexceeded. Theprovidedmethodofpaymentisnolongervalid(forexample,acreditcardhasexpired). MAX_ELEMENTS_EXCEEDEDindicatesthattheproductoforiginanddestinationexceedstheper-querylimit. INVALID_REQUESTindicatesthattheprovidedrequestwasinvalid. OVER_QUERY_LIMITindicatestheservicehasreceivedtoomanyrequestsfromyourapplicationwithintheallowedtimeperiod. REQUEST_DENIEDindicatesthattheservicedeniedtheuseoftheDistanceMatrixservicebyyourapplication. UNKNOWN_ERRORindicatesaDistanceMatrixrequestcouldnotbeprocessedduetoaservererror.Therequestmaysucceedifyoutryagain. Element-levelStatusCodes OKindicatestheresponseandcontainsavalidresult. NOT_FOUNDindicatesthattheoriginand/ordestinationofthispairingcouldnotbegeocoded. ZERO_RESULTSindicatesthatnoroutecouldbefoundbetweentheoriginanddestination. MAX_ROUTE_LENGTH_EXCEEDEDindicatesthattherequestedrouteistoolongandcannotbeprocessed. ErrorMessages Whenthetop-levelstatuscodeisotherthanOK,theremaybeanadditionalerror_messagefieldwithintheDistanceMatrixresponseobject.Thisfieldcontainsmoredetailedinformationaboutthereasonsbehindthegivenstatuscode. Rows WhentheDistanceMatrixAPIreturnsresults,itplacesthemwithinaJSONrowarray.Evenifnoresultsarereturned(suchaswhentheoriginsand/ordestinationsdon'texist),itstillreturnsanemptyarray.Rowsareorderedaccordingtothevaluesintheoriginparameteroftherequest.Eachrowcorrespondstoanorigin,andeachelementwithinthatrowcorrespondstoapairingoftheoriginwithadestinationvalue.Eachrowarraycontainsoneormoreelemententries,whichinturncontaintheinformationaboutasingleorigin-destinationpairing. Elements status:SeeStatusCodesforalistofpossiblestatuscodes. duration:Thelengthoftimeittakestotravelthisroute,expressedinseconds(thevaluefield)andastext. Theinformationabouteachorigin-destinationpairingisreturnedinanelemententry.Anelementcontainsthefollowingfields: duration_in_traffic:Thelengthoftimeittakestotravelthisroute,basedoncurrentandhistoricaltrafficconditions. distance:Thetotaldistanceofthisroute,expressedinmeters(value)andastext.Thetextualvalueusestheunitsystemspecifiedwiththeunitparameteroftheoriginalrequest,ortheorigin'sregion. EasytointegratetheDistanceMatrixAPI HowtomigratetoDistanceMatrix Start Ourcasestudies Thewaytoreducethecostoftheorderby30% TheDistanceMatrixAPI,distanceandfuelconsumptionoptimizationforthe"Waterbox"platform MaaSisthefutureoftransportation DistanceMatrix.aiAPIiscontributingtoanewtypeoffuturemobilityfromTurnn Optimizingtripsanddeliveryforsuppliersanddistributors TheDistanceMatrixAPIforSyrianapplicationfordrivers LearnmoreabouttheDistanceMatrixAPI LearnmoreabouttheDistanceMatrixAPI LearnmoreaboutDistanceMatrixAPI LearnmoreaboutDistanceMatrixAPI Nocreditcardrequired.Cancelanytime! Startafree7-daytrialoftheDistanceMatrixAPIforBusiness Getmy7-daysfreetrial Learnmoreaboutourpricing Getmy7-daysfreetrial Learnmoreaboutourpricing Products Resources Policiesandterms HowDistanceMatrixworks Ournews DistanceMatrixpricing Productdocumentation PrivacyPolicy FAQ Helparticles Videoguides Distancematrix.ai©2022.Allrightsreserved. PrivacyShieldPolicy CookiePolicy Products HowDistanceMatrixworks DistanceMatrixpricing FAQ Resources Ournews Productdocumentation Helparticles Videoguides PrivacyPolicy PrivacyShieldPolicy CookiePolicy Contactus Contactus HowAsynchronousDMworks HowAsynchronousDMworks HowGeocodingworks HowGeocodingworks Geocodingpricing Geocodingpricing Casestudies Casestudies