Alterra Dates API
API transport and endpoints
The API calls are done with JSON over HTTPS protocol using https://alterra.cc/api/dates endpoint. The client should issue a POST request with JSON-formatted body. The answer is also JSON-formatted.
JSON request format
The request data format is a JSON object with the following fields:
|version||Y||string||API version (use ‘v2’)|
|client_key||Y||string||API client key|
JSON response format (for version v2)
The response always has a “status” field, with values OK or ERR. If the value is ERR, an error has occurred. Details for the error can be found in “error” field. If the status is OK, it has one other field, named “parsed_query” (its format will follow shortly).
Dates API parses a user query and finds dates or date ranges inside it. We support both start/end dates and flexible dates (“from may 4 or 5 until may 21-23”). We also support duration-based ranges (“from may 4-7th for one week”). This can be rather ambiguous — we do our best to decipher what the user really meant.
Dates specified by numbers (20⁄12) can be either European (DD/MM) or US (MM/DD). If it is ambiguous, we mark that in the reply.
The date format is either “YYYY/MM/DD” for singe date, or “YYYY/MM/DD – YYYY/MM/DD” for date range.
Duration is returned in days, but can be an interval like “5 -7” (“I need a cruise starting in June for 2-3 weeks”)
The reply fields are these:
|begin_date||string||Date or date range of beginning of mentioned interval|
|end_date||string||Date or date range of end of mentioned interval|
|duration||string||Duration of the interval, if mentioned by user|
|date_ambiguity||bool||Whether we detected a date ambiguity|