Skip to content
/Distance Retriever

Street Route

Overview

The Street Route Cloud API provides a convenient online solution for retrieving the distance (measured in miles or kilometers) and estimated driving duration between two sets of latitude and longitude coordinates.

You can use Street Route to:

  • Find the distance and general drive time between two points
  • Create a ‘Find the Nearest Location’ tool.
    • Using a database of ‘known / owner destinations’, Street Route can be used to compare a starting point location to the database to return all the route distances and drive times to the possible destinations, which can be queried by the user to present the shortest distance or travel time to the end user.
  • Determine geolocations which our data sources tell us cannot be reached by vehicle travel.
    • This differentiates Street Route from other distance solutions which return ‘As the crow flies’ distances. Examples are geo points to islands, or rural off road residences.

Documentation

Useful Resources

Product Page

https://www.melissa.com/geocoding

Support Center

https://www.melissa.com/company/product-support

Download OpenAPI description
street-route.json
street-route.yaml
Languages
Servers
Street Route Server
https://streetroute.melissadata.net/v1/WEB/StreetRoute/

Distance Retriever

Use this endpoint to find the distance and general drive time between two points.

Operations

Get distance

Request

Uses HTTP GET to accept one input record and returns the response in JSON format.

Query
idstring(password)required

License Key - The License Key issued by Melissa.

Example: id={REPLACE-WITH-YOUR-LICENSE-KEY}
optstring

Options - List options in the following format, with multiple options delimited with a ,. For example: optionName:parameter,optionName:parameter. These options are case-sensitive and camel case.

  • arriveAt:< yyyy-mm-ddThh:mm:ss.mmmZ > - Specify the arrival time ISO 8601 UTC.

  • avoid:< borderCrossings | ferries | tollRoads | tunnels | unpavedRoads > - Specify the types of transport obstacles to avoid.

  • departAt:< yyyy-mm-ddThh:mm:ss.mmmZ | now > - Specify the departure date and time in ISO 8601 UTC. Default is now - departs immediately.

  • routeType:< eco | fastest | shortest | thrilling > - Specify the type of route.

    • eco - Balances travel time and fuel efficiency.
    • fastest - Optimizes for fastest travel time.
    • shortest - Optimizes for shortest travel distance.
    • thrilling - Optimized for challenging, hilly, or winding routes.

  • traffic:< false | true > - Considers current traffic conditions. Default is true.

  • travelMode:< bicycle | car | pedestrian > - Specify the type of vehicle used for the travel mode. Default is car.

  • vehicleCommercial:< false | true > - Indicates if the vehicle is a commercial vehicle. Default is false.

  • vehicleHeight:< [float] | 0 > - Specifies the vehicle height in meters. There are no height restrictions. Default is 0.

  • vehicleLength:< [float] | 0 > - Specifies the vehicle length in meters. Default is 0.

  • vehicleMaxSpeed:< [integer] | 0 > - Specifies the maximum vehicle speed in km/hr. Default is 0.

  • vehicleWeight:< [integer] | 0 > - Specifies the vehicle weight in kilograms. Minimum value is 1.

Example: opt=avoid:tunnels,routeType:shortest
tstring

Transmission Reference - Serves as a unique request identifier. It is returned as sent.

Example: t=Test
unitsstring

Units - This specifies the returned distance unit scale. Use mi for miles and km for kilometers.

Enum"mi""km"
Example: units=mi
endLatitudenumber(float)required

Ending Latitude - The street route ending latitude.

Example: endLatitude=33.64987
endLongitudenumber(float)required

Ending Longitude - The street route ending longitude.

Example: endLongitude=-117.58296
startLatitudenumber(float)required

Starting Latitude - The street route starting latitude.

Example: startLatitude=33.63752
startLongitudenumber(float)required

Starting Longitude - The street route starting longitude.

Example: startLongitude=-117.60692
curl -i -X GET \
  'https://streetroute.melissadata.net/v1/WEB/StreetRoute/getDistance?id={REPLACE-WITH-YOUR-LICENSE-KEY}&endLatitude=33.64987&endLongitude=-117.58296&startLatitude=33.63752&startLongitude=-117.60692'

Responses

Default response from a GET request

Bodyapplication/json
Resultsstring

Comma delimited status, error codes, and change codes for the record. For more information, see Street Route Result Codes.

Unitsstring

This is a string value that is the set unit of measurement for the TotalDrivingDistance field.

TransmissionResultsstring

Lists error codes from any errors caused by the most recent request as a whole. For more information, see Street Route Result Codes.

TravelTimestring

This is a string value of the travel time for the record in the format hh:mm:ss.

TotalDrivingDistancestring

This is a string value with the total driving distance. Refer to the Units field to know what unit of measurement it is.

TransmissionReferencestring

A pass-through of the input TransmissionReference field.

Versionstring

The current service version number.

Response
application/json
{
  "Results": "SR01",
  "Units": "mi",
  "TransmissionResults": "",
  "TravelTime": "00:05:05",
  "TotalDrivingDistance": "1.865353",
  "TransmissionReference": "Test",
  "Version": "8.2.1.0"
}

Get distance in batch

Request

Uses HTTP POST to accept multiple input records and returns the response in JSON format.

Bodyapplication/jsonrequired

Street Route Request Body

CustomerIDstringrequired

The License Key issued by Melissa.

Example: "{REPLACE-WITH-YOUR-LICENSE-KEY}"
Optionsstring

Options - List options in the following format, with multiple options delimited with a ,. For example: optionName:parameter,optionName:parameter. These options are case-sensitive and camel case.

  • arriveAt:< yyyy-mm-ddThh:mm:ss.mmmZ > - Specify the arrival time ISO 8601 UTC.

  • avoid:< borderCrossings | ferries | tollRoads | tunnels | unpavedRoads > - Specify the types of transport obstacles to avoid.

  • departAt:< yyyy-mm-ddThh:mm:ss.mmmZ | now > - Specify the departure date and time in ISO 8601 UTC. Default is now - departs immediately.

  • routeType:< eco | fastest | shortest | thrilling > - Specify the type of route.

    • eco - Balances travel time and fuel efficiency.
    • fastest - Optimizes for fastest travel time.
    • shortest - Optimizes for shortest travel distance.
    • thrilling - Optimized for challenging, hilly, or winding routes.

  • traffic:< false | true > - Considers current traffic conditions. Default is true.

  • travelMode:< bicycle | car | pedestrian > - Specify the type of vehicle used for the travel mode. Default is car.

  • vehicleCommercial:< false | true > - Indicates if the vehicle is a commercial vehicle. Default is false.

  • vehicleHeight:< [float] | 0 > - Specifies the vehicle height in meters. There are no height restrictions. Default is 0.

  • vehicleLength:< [float] | 0 > - Specifies the vehicle length in meters. Default is 0.

  • vehicleMaxSpeed:< [integer] | 0 > - Specifies the maximum vehicle speed in km/hr. Default is 0.

  • vehicleWeight:< [integer] | 0 > - Specifies the vehicle weight in kilograms. Minimum value is 1.

Example: "avoid:tunnels,routeType:shortest"
TransmissionReferencestring

Transmission Reference - Serves as a unique request identifier. It is returned as sent.

Example: "Test"
Unitsstring

Units - This specifies the returned distance unit scale. Use mi for miles and km for kilometers.

Example: "mi"
RecordsArray of objects[ 1 .. 100 ] itemsrequired

Array of request records.

Records[].​EndLatitudestring(float)required

The street route ending latitude.

Example: 33.64987
Records[].​EndLongitudestring(float)required

The street route ending longitude.

Example: -117.58296
Records[].​RecordIDstring

This is a string value containing a unique identifier for the current record. Use this to match the record submitted with the record returned. It will return what is inputted.

Records[].​StartLatitudestring(float)required

The street route starting latitude.

Example: 33.63752
Records[].​StartLongitudestring(float)required

The street route starting longitude.

Example: -117.60692
curl -i -X POST \
  https://streetroute.melissadata.net/v1/WEB/StreetRoute/getDistance \
  -H 'Content-Type: application/json' \
  -d '{
    "CustomerID": "{REPLACE-WITH-YOUR-LICENSE-KEY}",
    "Options": "avoid:tunnels,routeType:shortest",
    "TransmissionReference": "Test",
    "Units": "mi",
    "Records": [
      {
        "RecordID": "1",
        "StartLatitude": "33.637520",
        "StartLongitude": "-117.606920",
        "EndLatitude": "33.649870",
        "EndLongitude": "-117.582960"
      },
      {
        "RecordID": "2",
        "StartLatitude": "40.712776",
        "StartLongitude": "-74.005974",
        "EndLatitude": "34.052235",
        "EndLongitude": "-118.243683"
      }
    ]
  }'

Responses

Default response from a POST request

Bodyapplication/json
Versionstring

The current service version number.

Unitsstring

This is a string value that is the set unit of measurement for the TotalDrivingDistance field.

TransmissionReferencestring

A pass-through of the input TransmissionReference field.

TransmissionResultsstring

Lists error codes from any errors caused by the most recent request as a whole. For more information, see Street Route Result Codes.

TotalRecordsstring

Total number of records.

RecordsArray of objects

Array of output records.

Response
application/json
{
  "Version": "8.2.1.0",
  "Units": "mi",
  "TransmissionReference": "Test",
  "TransmissionResults": "",
  "TotalRecords": "2",
  "Records": [
    { … },
    { … }
  ]
}

Multipoint Distance Retriever

Use this endpoint to find the distance and general drive time between a start point and destination point with one or more waypoints. getDistanceMultipoint is currently available only as a GET request.

Operations