Thursday, May 30, 2013

HTTP status codes

As part of an ongoing effort to conform our web API design to industry best practices, we decided to take a closer look at the HTTP status codes that Eva returns.
The following is a list of the codes we currently use:
  • 200 OK = The request has succeeded. 
  • 400 BAD REQUEST = faulty values in the request parameters.
    Most often returned when the input_text field is empty.
  • 401 UNAUTHORIZED = The request requires user authentication, which failed.
    Please check the site_code and api_key request parameters.
  • 404 NOT FOUND = The server has not found anything matching the Request.
  • 405 METHOD NOT ALLOWED =  Eva currently supports only "HTTP GET" requests. 
  • 429 TOO MANY REQUESTS = The site_code quota has been exceeded.  See http://tools.ietf.org/html/rfc6585#section-4
  • 500 INTERNAL SERVER ERROR = A bug escaped us. Sorry. We are on it.
Please make sure your code can handle these return codes.

Wednesday, May 8, 2013

Changes to the "home" request argument

The "home" argument in the EVA API request is a great way specify where the end user is located when making the request.

Previously you were required to provide Geoname ID for the home location (based on http://www.geonames.org/) - for example to specify that the home is Rome you would need to send: "home=3169070" (http://www.geonames.org/3169070/rome.html).

From now on, you can either send the Geoname ID or the name of the home location - so for the previous example, you could just send: "home=rome".

Additional ways to specify user location are the longitude/latitude arguments and the ip_addr (IP address) argument.

For more information about this feature please refer to the Evature Documentation.

Wednesday, May 1, 2013


Eva's new timezone feature

From now on you have a way of specifying the end user's timezone with respect to the Coordinated Universal Time (UTC).
The timezone is very helpful in understanding expressions such as “hotel tonight”.
The value is a string representing the offset from UTC in the following format “+/-HH:MM”.
HH represents the hour offset in the range -12 to 14
MM represents the minutes offset
    
Examples:
    “time_zone=+08:00” means the UTC+8 timezone.
    “time_zone=-05:30” means the UTC-5:30 timezone

The timezone input can affect the resulting Eva reply. Here is an example:

With Timezone

  1.  {
  2.         "Arrival": {
  3.           "Date": "2013-05-02"
  4.         },
  5.         "Index": 10,
  6.         "Actions": [
  7.           "Get Accommodation"
  8.         ]
  9.       }

Without Timezone
http://freeapi.evature.com/v1.0?site_code=<your_site_code>&api_key=<your_api_key>&input_text=hotel%20tonight

  1.  {
  2.         "Arrival": {
  3.           "Date": "2013-05-01"
  4.         },
  5.         "Index": 10,
  6.         "Actions": [
  7.           "Get Accommodation"
  8.         ]
  9.       }


For more details on how to use this feature please read http://www.evature.com/docs/request.html

Changes to the hotel chains format


We changed the format of the Hotel Chains attribute.
The old format looked like this:

  1. "Hotel Attributes": {
  2.       "Chain": "Hilton Hotels"
  3.     }


A string with the formal name, as a global attribute in the API reply.
The new format looks like this:


  1. "Hotel Attributes": {
  2.           "Chain": [
  3.             {
  4.               "gds_code": "HH",
  5.               "Name": "Hilton Hotels",
  6.               "eva_code": "EPC-47"
  7.             }
  8.           ]
  9.         }


The new format allows for simpler integration with client databases.
We have also moved the chain attribute to be location-related and it is no longer a global attribute.
This allows Eva to address complex itineraries, such as "2 nights in rome. hilton. 3 nights in paris. sheraton"

The changes will be part of the next revision of the API.

To preview the change and ease the integration we added a new "from future" request attribute.
Add ffi_chains to the request query and the API reply will contain the new chain format.

Example:
http://freeapi.evature.com/v1.0?site_code=a_site_code&api_key=an_api_key&ffi_chains&input_text=ny%20hilton