Requests

How to make requests against v2 endpoints

Endpoints

Below you'll find descriptions for all available endpoints:

• distance/route: Car routing and airline distance

• distance/route/detailed: Detailed car routing with route breakdown

• distance/route/maritime: Maritime sea route distances

• distance/point: Geocoding and point information

Sandbox

https://rapidapi.com/Distance.to/api/distance

distance/route

Car routing and airline distance

POST https://distanceto.p.rapidapi.com/distance/route

Calculate airline and car routing distances between multiple points.

Query Parameters

Name	Type	Description
car	Boolean	get car routing distances
flight	Boolean	get flight distances
equal	Boolean	get equal distances

Headers

Name	Type	Description
X-RapidAPI-Key*	String	your Rapid API key
X-RapidAPI-Host*	String	distanceto.p.rapidapi.com

Request Body

Name	Type	Description
route*	JSON	route object containing waypoint information. See description below.

200: OK Valid request and found waypoints

{
  "route": {
    "vincenty": 256.364,              // airline distance in KM
    "haversine": 255.6544674163047,   // airline distance in KM
    "greatCircle": 255.65447544186136,// airline distance in KM
    "car": {
      "distance": 284.128,            // car routing distance in KM
      "duration": 11362.1,            // car routing duration in Sec 
      "status": "found"               // flag indicating route was found
    }
  }
  "steps": [ ... ],
  "points": [ ... ]
}

404: Not Found Valid request but waypoints not found

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Could not geocode all requested steps."
}

400: Bad Request Invalid request

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation: Description of failed input validation"
}

Request Body

{
  "route": [{
    "name": "Berlin",  // Required: Any input text or lat,lng
    "country": "DEU"   // Optional: ISO 3166-1 alpha-3 country code
  }, {
    "name": "Hamburg", // Required: Any input text or lat,lng
    "country": "DEU"   // Optional: ISO 3166-1 alpha-3 country code
  }]
}

Learn more about the request body payload and about input data here.

distance/route/detailed

Car routing and airline distance

POST https://distanceto.p.rapidapi.com/distance/route/detailed

Calculate car routing distances between cities, addresses or postal codes with detailed country breakdown.

Headers

Name	Type	Description
X-RapidAPI-Key*	String	your Rapid API key
X-RapidAPI-Host*	String	distanceto.p.rapidapi.com

Request Body

Name	Type	Description
route*	JSON	route object containing waypoint information. See description below.

200: OK Valid request and all waypoints found

{
  "steps": [ ... ],
  "points": [ ... ],
  "route": {
    "vincenty": 839.042,              // airline distance in KM
    "haversine": 837.8439064749667,   // airline distance in KM
    "greatCircle": 837.8439327767333, // airline distance in KM
    "car": {
      "distance": 983.968,            // car routing distance in KM
      "duration": 47253.3,            // car routing distance in Sec.
      "midpoint": {
        "distance": 491.984,          // distance in KM
        "coordinates": [12.829923011995646,56.12948896450904]
    },
    "countries": [{
      "country": "NO",
      "distance": 115.5178432,        // driving distance in KM
      "duration": 5547.537420000001   // driving duration in Sec.
    }, {
      "country": "DK",
      "distance": 208.0108352,        // driving distance in KM
      "duration": 9989.34762          // driving duration in Sec.
    }, {
      "country": "DE",
      "distance": 252.09260159999997, // driving distance in KM 
      "duration": 12106.29546         // driving duration in Sec. 
    }, {
      "country": "SE",
      "distance": 396.04712,          // driving distance in KM
      "duration": 19019.453250000002  // driving duration in Sec.
    }]
   }
 }

404: Not Found Valid request but not all waypoints were found

{
	"statusCode": 404,
	"error": "Not Found",
	"message": "Could not geocode all requested steps."
}

400: Bad Request Invalid request

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation: Description of failed input validation"
}

Request body

{
  "route": [{
    "name": "Berlin", // Required: Any input text or lat,lng
    "country": "DEU"  // Optional: ISO 3166-1 alpha-3 country code
  }, {
    "name": "Oslo",   // Required: Any input text or lat,lng
    "country": "NOR"  // Optional: ISO 3166-1 alpha-3 country code
  }]
}

Learn more about the request body payload and about input data here.

distance/route/maritime

Maritime route and airline distance

POST https://distanceto.p.rapidapi.com/distance/route

Get maritime route distances. Points will be matched to the nearest sea route vertex.

Headers

Name	Type	Description
X-RapidAPI-Key*	String	your Rapid API key
X-RapidAPI-Host*	String	distanceto.p.rapidapi.com

Request Body

Name	Type	Description
route*	JSON	route object containing waypoint information. See description below.

200: OK Valid request and found waypoints

{
  "steps": [ ... ],
  "points": [ ... ],
  "route": {
    "vincenty": 839.042,                // airline distance in KM
    "haversine": 837.8439064749667,     // airline distance in KM 
    "greatCircle": 837.8439327767333,   // airline distance in KM
    "sea": {
      "distance": 960.2291039330195,    // maritime distance in KM
      "distanceNM": 518.4824262723614,  // maritime distance in NM
      "duration": 25.92412131361807,    // travel time in hours
      "status": "found"                 // flag indicating a maritime was found 
    }
  }
}

400: Bad Request Invalid request

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation: Description of failed input validation"
}

404: Not Found Valid request but not all waypoints were found

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Could not geocode all requested steps."
}

Request body

{
  "route": [{
    "name": "Hamburg",  // Required: Any input text or lat,lng
    "country": "DEU"    // Optional: ISO 3166-1 alpha-3 country code
  }, {
    "name": "Oslo",     // Required: Any input text or lat,lng
    "country": "NOR"    // Optional: ISO 3166-1 alpha-3 country code
  }]
}

Learn more about the request body payload and about input data here.

distance/point

Get point information

POST https://distanceto.p.rapidapi.com/distance/point

Get geocoding and information about a geographical point.

Query Parameters

Name	Type	Description
airports	Boolean	get nearby airports
cities	Boolean	get nearby cities
furthest	Boolean	get furthest cities

Headers

Name	Type	Description
X-RapidAPI-Key*	String	your Rapid API key
X-RapidAPI-Host*	String	distanceto.p.rapidapi.com

Request Body

Name	Type	Description
point*	JSON	point object containing waypoint information. See description below.

200: OK Valid request and point found

{
  "points": [{
    "type": "Feature",
    "properties": {
      "type": "postcode",
      "geocode": {
        "countrycode": "DE",
        "postalcode": "12055",
        "placename": "Berlin",
        "admin1name": "Berlin",
        "admin1code": "BE",
        "admin2name": null,
        "admin2code": "00",
        "admin3name": "Berlin, Stadt",
        "admin3code": "11000",
        "accuracy": 6,
        "latitude": 52.47185975,
        "longitude": 13.44744399955233,
        "tz": "Europe/Berlin",
        "regions": [{
          "id": 51477,
          "name_en": "Germany",
          "name": "Deutschland",
          "level": 2,
          "int": "Germany"
        }, {
          "id": 62422,
          "name_en": "Berlin",
          "name": "Berlin",
          "level": 4,
          "int": "Berlin"
        }, {
							"id": 409213,
							"name_en": null,
							"name": "Neukölln",
							"int_name": null,
							"level": 10,
							"int": "Neukölln"
						}
					]
				},
				"stats": {
					"antipodia": [
						-166.55255600044768,
						-52.47185975
					],
					"equator": {
						"distance": 5834.6126549039345,
						"bearing": "S"
					},
					"northpole": 4172.944566114027,
					"southpole": 15843.251289093756
				}
			},
			"geometry": {
				"type": "Point",
				"coordinates": [
					13.44744399955233,
					52.47185975
				]
			}
		}
	]
}

Request body

{
  "point": {
    "name": "Berlin",  // Required: Any input text or lat,lng
    "country": "DEU"   // Optional: ISO 3166-1 alpha-3 country code
  }
}

Learn more about the request body payload and about input data here.