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:

Field Name Required Type Comment
message Y string User’s message
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 (2012) 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:

Field Name Type Comment
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