Using HTTP POST
The Directions API and Map Matching API both support access using the HTTP POST method. HTTP POST should be used for large requests, since both the Directions and Map Matching APIs have a size limit of approximately 8100 bytes on GET request URLs. POST requests are still subject to your account's request size limits.
If your request falls within the default limits (25 for Directions API requests using driving, walking, and cycling profiles or 3 for request using the driving-traffic profile; 100 for Map Matching API requests), a GET request will work for you and you do not need to use POST. If your account limits are larger than these defaults and you receive an HTTP 413 ("Request entity too large") or HTTP 414 ("Request URL too large") error when you make a GET request to either API, then using POST is a good option for you.
To submit a request using HTTP POST, make the following changes to the request:
- The HTTP method must be
POST. - The
Content-Typeof the request must beapplication/x-www-form-urlencoded. - The coordinate list must be present in the request body as the
coordinates=parameter. Do not put coordinates in the URL. - The
access_tokenparameter must be part of thePOSTURL, not the body. All other parameters must be part of the request body.
A POST request for the Map Matching API or the Directions API looks like this:
POST /{api_name}/{api_version}/mapbox/{profile}?access_token={your_access_token} HTTP/1.0
Content-Type: application/x-www-form-urlencoded
coordinates={lon1,lat1;lon2,lat2;...;lonN,latN}
Example HTTP POST requests
# POST request to Map Matching API
$curl -d "coordinates=-117.17282,32.71204;-117.17288,32.71225;-117.17293,32.71244;-117.17292,32.71256;-117.17298,32.712603;-117.17314,32.71259;-117.17334,32.71254" "https://api.mapbox.com/matching/v5/mapbox/driving?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
# POST request to Directions API with optional parameters
$curl -d "coordinates=2.344003,48.85805;2.34675,48.85727;2.34868,48.85936;2.34955,48.86084;2.34955,48.86088;2.349625,48.86102;2.34982,48.86125&steps=true&waypoints=0;6&waypoint_names=Home;Work&banner_instructions=true" "https://api.mapbox.com/directions/v5/mapbox/driving?access_token=YOUR_MAPBOX_ACCESS_TOKEN"