Alexa AMAZON.DATE and Node.js

4 min readJun 18, 2017

How to handle the AMAZON.DATE slot with your Node.js Amazon Alexa skill.

If you came across Amazon Alexa skill development with Node.js you would probably experience some problem handling the AMAZON.DATE slot.

The AMAZON.DATE slot can be used in a lot of different tasks: to retrieve an event for a specific date, to query a calendar, to check a booking reservation and so on.

AMAZON.DATE representation

The AMAZON.DATE slot converts words that represent dates into a date format. Below a complete list of conversion:

“right now”: PRESENT_REF
“today”: 2017–11–24
“tomorrow”: 2017–11–25
“november twenty-fifth”: 2017–11–25
“next monday”: 2017–11–30
“this week”: 2017-W48
“next week”: 2017-W49
“this weekend”: 2017-W48-WE
“this month”: 2017–11 and 2019–11-XX
“next year”: 2018 and 2019-XX
“this decade”: 201X
“next winter”: 2018-WI
“this summer”: 2017-SU
“this autumn”: 2017-FA //as Fall
“this spring”: 2017-SP
“this quarter”: 2019-Q1

You can find more info at the Amazon slot type reference guide.

AMAZON.DATE and JS Date Object

Assuming you are handling dates with the Javascript Date object, the first problem is that you cannot use an AMAZON.date value “as it is”.

For instance, the following snippet returns “Invalid Date”:

new Date('2017-W50');new Date('PRESENT_REF');

Another issue is related to representations like “this week” or “this weekend” which are expressions of a specific start and end point. To clarify this case, imagine you want to retrieve from a database a list of movies on cinema for this weekend. Probably, you should query the db with the following pseudo-SQL code: `Select movies between this Saturday and this Sunday`.

How to handle all those issues?
With the amazon-date-parser.

The Amazon date parser

The amazon-date-parser is an useful npm package (more info here). It converts the AMAZON.DATE slot value to a JS object composed by a startDate and an endDate i.e.:

var AmazonDateParser = require('amazon-date-parser');var date = new AmazonDateParser('2017-W48');console.log(date);/* returns:{ endDate: Sun Dec 03 2017 23:59:59 GMT+0000 (GMT),  startDate: Mon Nov 27 2017 00:00:00 GMT+0000 (GMT) }*/

The startDate and endDate values are JS Date objects, and that is great for futher date conversion:

//following to the previous script below a conversion exampleconsole.log(date.startDate.toLocaleDateString('en-US')); 
// returns “11/27/2017”console.log(date.endDate.toLocaleDateString('en-GB')); 
// returns “12/3/2017”

Handling seasons

The library handles seasons’s periods as well but, since the concept of season can vary based its context at the moment only metheorological seasons are supported.
So, what is a season. Well, it depends…

Meteorological seasons
For a “meteorological perspective” a season is based on a specific weather conditions, temperatures, or length of the days. So for People in the southern hemisphere, like Australia or Brazil the summer begins the 1st of December.

Meteorological Seasons are mainly divided in:

Spring — from March 1 to May 31;
Summer — from June 1 to August 31;
Fall/Autumn — from September 1 to November 30;
Winter — from December 1 to February 28 (February 29 in a leap year).

Astronomical seasons

Astronomical seasons are based on the dates of equinoxes and solstices.
In the northern hemisphere, the four astronomical seasons are:

Spring — March Equinox to June Solstice;
Summer — June Solstice to September Equinox;
Fall/Autumn — September Equinox to December Solstice;
Winter — December Solstice to March Equinox.

If you want to handle astronomcal seasons the npm library season-dates is what you are looking for.

Alexa skill usage example

At this point, probably you are thinking about how to use this library in your next Alexa skill, I believe the following code snippet will give you an idea:

var AmazonDateParser = require('amazon-date-parser');//...'searchIntent': function () {
    var slotValue = this.event.request.intent.slots.date.value;
    var dateRange = new AmazonDateParser(slotValue);//.../*
At this point you can use dateRange.startDate and dateRange.endDate to query an API or a database.
*/

Following, a sample Alexa intent schema.

{
  "intents":  [
     { "intent": "AMAZON.HelpIntent", "slots": [] },
     { "intent": "AMAZON.StopIntent", "slots": [] },
     { "intent": "AMAZON.CancelIntent", "slots": [] },
     { "intent": "AMAZON.YesIntent", "slots": [] },
     { "intent": "AMAZON.NoIntent", "slots": [] },
     { "intent": "searchIntent", "slots": [
       { "name": "date", "type": "AMAZON.DATE" }
     ]}
  ]
}

So what are you waiting for? Add the library to your dependencies and share a feedback!

npm install amazon-date-parser