Upcoming new API version for better entity format

26 Sep 2014 update

Next week, we’ll be releasing a new version of the API which should make it easier to work with entities such as datetime. The changes in the new version (version 20141021) will only affect the entities field in the outcome object when you receive a response from Wit.ai. To update to the new version, you’ll need to 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=20141021&q=hello'

or

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

The new format will make 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 will look like the following:

curl   -H 'Authorization: Bearer $TOKEN   'https://api.wit.ai/message?v=20141021&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”}


Once we release the new version of the 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. 20141021) at which point they will be removed from our system.

Please contact us if you have any questions or concerns.

Team Wit