New API Version Released

22 Oct 2014 update

We’ve released a new version of the API which will make working with entiites like datetimes easier. The new API version (version 20141022) only affects the entities field in the outcome object when you receive a response from Wit.ai. To update to the new version, change your version number in the call to the API. The new way to call the API will be:

bash curl -H ‘Authorization: Bearer $TOKEN’ ‘https://api.wit.ai/message?v=20141022&q=hello'

or

bash curl -H 'Authorization: Bearer $TOKEN' -H 'Accept: application/vnd.wit.20141022+json' 'https://api.wit.ai/message?q=hello'

The new format makes it easier for you to parse entities but also paves the way for more information for many entities such as datetime. To compare, if we pass the phrase “Set alarm tomorrow at 7am” to Wit.ai, the response from the old API version (v. 20140620) might look like this:

 curl   -H 'Authorization: Bearer $TOKEN   'https://api.wit.ai/message?v=20140620&q=set%20alarm%20tomorrow%20at%207am'

{
  "msg_id" : "dcdac1af-adad-41dd-aeb6-c40f29a20e08",
  "_text" : "set alarm tomorrow at 7am",
  "outcomes" : [ {
    "_text" : "set alarm tomorrow at 7am",
    "intent" : "alarm_set",
    "entities" : {
      "on_off" : [ {
        "value" : "on"
      } ],
      "datetime" : [ {
        "value" : {
          "from" : "2014-09-27T07:00:00.000-07:00",
          "to" : "2014-09-27T08:00:00.000-07:00"
        }
      } ]
    },
    "confidence" : 0.995
  } ]
}

In the new version, the response looks like the following:

curl   -H 'Authorization: Bearer $TOKEN   'https://api.wit.ai/message?v=20141022&q=set%20alarm%20tomorrow%20at%207am'

{
  "msg_id" : "07a8edd6-3503-4fc7-857d-bc506b85c720",
  "_text" : "set alarm tomorrow at 7am",
  "outcomes" : [ {
    "_text" : "set alarm tomorrow from 7am",
    "intent" : "alarm_set",
    "entities" : {
      "datetime" : [ {
        "type" : "value",
        "value" : "2014-09-27T07:00:00.000-07:00",
        "grain" : "hour",
      } ],
      "on_off" : [ {
        "value" : "on"
      } ]
    },
    "confidence" : 0.999
  } ]
}

The table below illustrates all of the changes in the new API response:

Example   Current format   New format
on July 15th at 5pm (Datetime)   {“value” :
{“from” : “2015-07-15T17:00:00.000-07:00”, “to” : “2015-07-15T18:00:00.000-07:00”}}
  {“type” : “value”,
“value” : “2013-07-15T17:00:00.000-02:00”,
“grain” : “hour”}
from 7am to 8am (Datetime)   {“value” : {“from” : “2014-09-26T06:00:00.000-07:00”, “to” : “2014-09-26T07:00:00.000-07:00”}}   {“type” : “interval”,
“from” : {“value” : “2014-09-26T07:00:00.000-02:00”, “grain” : “hour”},
“to” : {“value” : “2014-09-26T08:00:00.000-02:00”, “grain” : “hour”}}
this afternoon(Datetime)   {“value” : {“from” : “2014-09-26T12:00:00.000-07:00”,”to” : “2014-09-26T19:00:00.000-07:00”}}   {“type” : “interval”,”from” : {“value” : “2014-09-26T12:00:00.000-02:00”, “grain” : “hour”},”to” : {“value” : “2014-09-26T19:00:00.000-02:00”, “grain” : “hour”}}
2 hours (Duration)   {“value” : 7200}   {“type” : “value”, “unit” : “hour”, “value” : 2, “normalized” : {“value” : 7200, “unit” : “second”}}
70 degrees (Temperature)   {“value” : {“temperature” : 70}}   {“type” : “value”, “unit” : “degree”, “value” : 70}
70°C (Temperature)   {“value” : {“temperature” : 70,”unit” : “C”}}   {“type” : “value”, “unit” : “celsius”, “value” : 70}
70 (as an implicit Temperature)   {“value” : {“temperature” : 70}}   {“type” : “value”, “value” : 70}
30 miles (Distance)   {“value” : {“unit” : “miles”,”distance” : 30}}   {“type” : “value”, “unit” : “mile”, “value” : 30}
30 (Quantity or Number)   {“value” : 30}   {“type” : “value”,”value” : 30}
about $20 (Amount_of_money)   {“value” : {“currency” : “$”,”amount” : 20}}   {“type” : “value”, “unit” : “$”, “value” : 20}
one cup of sugar (Quantity)   {“value” : {“product” : “sugar”,”unit” : “cups”,”value” : 1}}   {“type” : “value”, “unit” : “cup”, “value” : 1, “product” : “sugar” }
350ml (Volume)   {,”value” : {,”unit” : “litre”,,”volume” : 23,},}   {“type” : “value”, “value” : 330, “unit” : “millilitre”}


With the release of the new API, any old versions ( any version < 20120924) will be deprecated and a field ‘WARNING’ with the value ‘DEPRECATED’ will be added to any response from a request with an old version. Old API versions will persist until the next subsequent API update (the version after v. 20141022) at which point they will be removed from our system.

Please contact us if you have any questions or concerns.

Team Wit