Skip to main content

Using HTTP POST

Additional Developer Resources

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-Type of the request must be application/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_token parameter must be part of the POST URL, 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"
Additional Developer Resources
Was this page helpful?