About

Natural Inputs is an API that extracts date, time, and message information from naturally worded text.

Getting the source

The source is available, with a permissive licence, in a gem called Nickel.

Why you should use it

  • Simplify any form with date and time inputs
  • Increase your website's usability
  • Handles recurring date and time information

Ruby Requests 

sudo gem install nickel

Then:

n = Nickel.parse "Stupid meeting on july 1st at 9am")
n.message #=> "Stupid meeting"
n.occurrences[0].start_date #=> "20110701"
n.occurrences[0].start_time #=> "09:00:00"

Usage Notes

Make a GET request with your query appended as follows:

http://www.naturalinputs.com/query?k=API_KEY&t=CURRENT_TIME&q=lunch+tomorrow+at+noon

The current time parameter should be in the following format:

yyyyMMddThhmmss

For example, November 5, 2008 at 2pm would look like this:

20081105T140000
Instructions for making request (Ruby)

Returned XML

a guess at the message intended by the user

  • type:possible values: single, daily, weekly, daymonthly, datemonthly (examples below)
  • start_date:the first occurrence, in "yyyymmdd" format
  • end_date:the last occurrence, in "yyyymmdd" format
  • start_time:start time on 24hr clock
  • end_time:end time on 24hr clock
  • interval:interval of recurrence, for example "every other day" will have an interval of 2 (N/A for single date)
  • day_of_week:day of the week for weekly and daymonthly recurrences
  • week_of_month:daymonthly recurrences only, indicates week number. Possible values are 1,2,3,4,-1; -1 indicates the last week of the month
  • date_of_month:datemonthly recurrences only. Possible values are 1 through 31

Occurrence type

Occurrence type has possible values of: single, daily, weekly, daymonthly, datemonthly.

Some examples of each should suffice:

  • single "lunch with megan tomorrow at noon"
  • daily "Art exhibit until March 1st"
  • weekly "math class every wed from 8-11am"
  • daymonthly "open bar at joes the first friday of every month"
  • datemonthly "pay credit card bill on the 22nd of each month"

Occurrence interval

  • Most cases will have an interval of 1, for example: "every wednesday", "the 21st of every month", or "every day".
  • An interval of 2 would be something like: "every other friday", "the first tuesday of every other month", or "every other day"
  • An inteval of 3 would be something like: "every three weeks starting this friday"

Advanced Queries

Natural Inputs can handle some pretty complicated queries, which could be useful for calendaring or scheduling apps. For instance, many date/time parsers can handle single occurrences, but how about something that happens multiple times like "the first tuesday of every month"? Although this won't be necessary in many cases, it's good to know that the option is there.

Some Examples:

  • At 3pm on the first and last thursday of every month
  • Every monday and wed from 3 to 6pm and again at 10
  • June 6th at 7am, 7/24 at noon, and 8/29/2009 at 6:30pm
  • Every other friday at 7 am until december 12
  • The 21st, 22nd, and 24th of each month between 4 and 6am

Support & FAQs

Natural Inputs was written by Lou Zell. Feel free to contact him with failing cases, questions, or feedback of any type. To get his email address, punch "email" into the demo bar above.