Anniversarator

you can use it as a web service

The Anniversarator web page can also be used as a simple REST web service by third-party applications. This means that if you have a facebook application, a mobile application, or some other web service, and you want to be able to incorporate the results of the Anniversarator's calculations into your application, you can do that using a simple HTTP call to the page with the appropriate parameters.

A simple query: retrieving today's special occasion.

To get the simplest response from the Anniversarator web service, to find out what special occasion you can celebrate today, you have to perform an HTTP GET operation to the base URL of the page and specify five parameters in the query string portion of the URL:

parametermeaningvaluesdefault
tthe type of date provided"birthday" or "anniversary""anniversary"
ythe year of date provided4 digit format, 1900 or laternone
mthe month of date provided2 digit format, 01 to 12none
dthe day of date provided2 digit format, 01 to 31none
formatthe format you want your results in"xml","html", or "text""html"

The Anniversarator actually produces two types of output: the main message and an annotation. The annotation may be blank, but may contain text to explain some of our more esoteric anniversary calculations. For example, if the message says, "Today is your 100 fortnight Anniversary! You should celebrate!" then the annotation will contain text that explains, "A fortnight is equal to 2 weeks, or 14 days".

So, when the HTTP GET operation is performed on the URL, the service will return the results in one of the following formats:

So, for example, if you wanted your application to use our web service to get a plain text message for the anniversary based on a relationship date of 2/1/2011, your would HTTP GET the following URL:

http://anniversarator.com/?t=anniversary&m=02&d=01&y=2011&format=text

The results returned by this call will be a simple plain text string. For example, if today's date were February 15, 2011, the result might be a plain text string that says,

Today is your 1 fortnight anniversary! You should celebrate! A fortnight is a period of 2 weeks, or 14 days.

On the other hand, if you wanted to get more detailed results formatted as an XML document, you could use the following call to the web service,

http://anniversarator.com/?t=anniversary&m=02&d=01&y=2011&format=xml

The results returned by this call will be a short XML document using the following format:

<anniversarator>
 <occasion>
  <date-type>anniversary</date-type>
  <date-given>2011-02-01</date-given>
  <date-requested>2011-02-15</date-requested>
  <message>This is your 1 fortnight anniversary! You should celebrate!</message>
  <annotation>A fortnight is a period of 2 weeks, or 14 days.</annotation>
 </occasion>
</anniversarator>

This simple type of call, with only five parameters, reproduces all of the functionality for the "basic" options on the home page web interface. This next section will describe the additional parameters to use if you want to reproduce the "advanced" options on the home page using the web service.

An advanced query: retrieving a list of special occasions.

The simple query returns the text for a single special occasion: today. You can also have the Anniversarator return a list of special occasions by identifying the date of the first special occasion you are interested in and the number of days total to return. These are identified with the following additional four parameters:

parametermeaningvaluesdefault
nnumber of occasions to returnany positive integer1
_ythe year of first occasion to calculate4 digit format, 1900 or laternone
_mthe month of first occasion to calculate2 digit format, 01 to 12none
_dthe day of first occasion to calculate2 digit format, 01 to 31none

So, for example, suppose you have a relationship that began on March 15, 2000, and you will be going on a three-day vacation on January 15, 2002. You would like to know what special occasions you can use as an excuse to celebrate each day of your vacation. To get the results as a series of lines of plain text, you would call this URL with your web application:

http://anniversarator.com/?t=anniversary&m=03&d=15&y=2000&_m=01&_d=15&_y=2002&n=3&format=text

This will return the following 3 lines of plain text:

1/15/2002 is your 22 month anniversary! You should celebrate! 
1/16/2002 is your 48 fortnight anniversary! You should celebrate! A fortnight is 2 weeks, or 14 days.
1/17/2002 is your 3 year anniversary, in Venusian years! You should celebrate! A Venusian year, the amount of time it takes Venus to circle the sun, is 224.7 Earth days.

On the other hand, if your web application can make parse XML documents as input, you may want to request these results as an XML document:

http://anniversarator.com/?t=anniversary&m=03&d=15&y=2000&_m=01&_d=15&_y=2002&n=3&format=xml

This will produce an XML document that consists of a list of three <occasion> elements, one for each special occasion!

<anniversarator>
 <occasion>
  <date-type>anniversary</date-type>
  <date-given>2000-03-15</date-given>
  <date-requested>2002-01-15</date-requested>
  <message>Today is your 22 month anniversary! You should celebrate!</message>
  <annotation/>
 </occasion>
 <occasion>
  <date-type>anniversary</date-type>
  <date-given>2000-03-15</date-given>
  <date-requested>2002-01-16</date-requested>
  <message>Today is your 48 fortnight anniversary! You should celebrate!</message>
  <annotation>A fortnight is 2 weeks, or 14 days.</annotation>
 </occasion>
 <occasion>
  <date-type>anniversary</date-type>
  <date-given>2000-03-15</date-given>
  <date-requested>2002-01-17</date-requested>
  <message>Today is your 3 year anniversary, in Venusian years! You should celebrate!</message>
  <annotation>A Venusian year, the amount of time it takes Venus to circle the sun, is 224.7 Earth days.</annotation>
 </occasion>
</anniversarator>

Error conditions.

If you enter bad parameters that prevent the result from calculating properly, you will receive and error message with an error code. The error codes are as follows:

error codeerror description
1You have not specified a valid date to start counting from.
2You have not specified a valid date to calculate for.
3You have not specified a valid number of result days to return.
4You have not specified a valid date type.

The way that the result is displayed depends on the result format you have selected. If you choose plain text, then the error code and message are given as a single line of plain text.

So, for example, the following HTTP GET requests plain text format results, but is missing some date information (the day number is not provided):

http://anniversarator.com/?t=anniversary&m=01&y=2008&format=text

This will result in a single line of text being returned:

ERROR CODE 1: You have not specified a valid date to start counting from. You must specify the month, day, and year that you were born (for birthdays) or that the relationship started (for anniversaries).

If you select XML as the result format, you will receive a short XML document with the error code and error message specified:

<anniversarator errorcode="1">
 <message>You have not specified a valid date to start counting from.</message>
 <annotation>You must specify the month, day, and year that you were born (for birthdays) or that the relationship started (for anniversaries).</annotation>
</anniversarator>

If you specify an invalid result format, the system will simply return a plain text message saying, "Invalid format requested."

And that's it! It's as simple as that.

If you have any questions about using this web service, please let me know at webmaster@anniversarator.com.

Thank you for using the service, and have fun!

Return to the Anniversarator