Planning Receive API

Context

The Planning Receive API is a unified interface where you post your planning to. You should be aware of the format we would expect from you.

Environment

For the Planning Receive API we use the following URIs:

Production URL :
https​://planning-receive-api.services.simacan.com/trips/insertOrUpdate
Staging URL :
https:​//planning-receive-api-stg.services.simacan.com/trips/insertOrUpdate

OTM5 Production URL :
https​://planning-receive-api.services.simacan.com/otm/api/v5/trips
OTM5 Staging URL :
https:​//planning-receive-api-stg.services.simacan.com/otm/api/v5/trips

Schema

The planning-receive-api supports two type of planning formats:

1. OpenTripModel version 5, which is an open standard we support within Simacan.
2. 'schema-less' endpoints for XML, JSON and CSV. Where we accept any file with those formats and do not check for any schema at all.

You can find the exact details on our OpenAPI specification page.

Example

Sending your planning

As mentioned before, you should have requested your access_token from the Auth API. Next, make sure you are setting the correct headers and request type for the filetype you are sending, so set your Content-Type to one of the following:

• For more info on the structure for the CSV file, see our guide
• For more info on the structure for the JSON file, see our other guide

Send it

Keep in mind that this request only works, if you have a bearer token and set the correct Content-Type. Include these in the header. The content of the request should be in the body of the message. In this example we post to the staging URL:

curl 
  --header "Content-Type: text/csv" \
  --header "Authorization: Bearer eyXXX" \
  --data-raw "trip ID,STOP ID,location ID,start time stop,END time stop
1,Stop1,1,2021-01-25T10:00:00+01:00,2021-01-25T10:00:00+01:00
1,Stop2,2,2021-01-25T10:45:00+01:00,2021-01-25T11:00:00+01:00
1,Stop3,1,2021-01-25T11:30:00+01:00,2021-01-25T11:45:00+01:00" \
  --request POST \
  https://planning-receive-api-stg.services.simacan.com/trips/insertOrUpdate

curl 
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer eyXXX" \
  --data-raw "{
    \"id\": \"2a8af6c6-e4d5-5dfb-9532-e8b17c3ffd88\",
    \"name\": \"2021-32-2-888\",
    \"externalAttributes\": {},
    \"actors\": [],
    \"actions\": []
    }"
  --request PUT \
  https://planning-receive-api-stg.services.simacan.com/otm/api/v5/trips

curl 
  --header "Content-Type: text/xml" \
  --header "Authorization: Bearer eyXXX" \
  --data-raw "YOUR_XML_DATA_HERE" \
  --request POST \
  https://planning-receive-api-stg.services.simacan.com/trips/insertOrUpdate

Response

If everything went fine, you should receive an HTTP status code 200 OK and a body which looks like this

01b44637-1395-4591-a0ec-14108022b707

Great! Your planning has been delivered to our platform. On success you will get the UUID for the specific file you've just sent us. Keep in mind, this is just a confirmation that we received your file. This is not a confirmation that your planning is processing.

To see the status of your delivered file, check the next chapter on the Planning Status API.

Responses