Adegga

Introduction

The Adegga API provides a simple RESTful interface with XML and Json formatted responses to use many of Adegga’s website features, including producers, wines, country and wine types. This document provides information to developers on how to integrate with the Adegga API.

Concepts

Authentication
The Adegga API requires a developer key which you can ask us using this request form. The key identifies you as a unique entity making calls against the Adegga web service, and is used to track overall call usage. Currently, the available API methods access public information, so there is no additional authentication needed.

Terms of Service
For more information please read the API Terms of Service.

HTTP requests
The Adegga API uses a RESTful calling style that works with standard HTTP GET calls. (Future versions of the Adegga API will use additional HTTP methods.) Any web programming language (PHP, Ruby, Perl, Python, C#, VB, Java…) should be able to make and receive HTTP networking calls; consult the documentation for your language of choice.

Rate limiting
Clients are allowed 1000 requests per day. If your application needs more than the allotted amount of calls, contact us at dev@adegga.com with a description of the application and an estimate on call usage. (You might also want to investigate the use of caching to keep the number of calls to a minimum, and make your application more responsive.)

Pagination limiting
The default set of returned records in a call is 100.

Encoding
The Adegga API uses both JSON, a lightweight data serialization language that is compatible with many different languages, and XML a standard inter system serialization language.

How to make a request and process the response

Here’s a step-by-step example of how to make a request to the Adegga API. We’ll make a request to get details for a wine called “Cortes de Cima Reserva 2003″ with an avin = AVIN6452997073019. Using the GetWineByAvin method. If you consult the documentation for that method, you’ll see something like this:

GetWineByAvin

Every Adegga API request begins with the base URL: api.adegga.com/rest/v1.0 and ends with the URI for the command.

Finally, you’ll add a and symbol (“&”) plus any optional parameters you’d like to send (in this case, format), and of course, your API key (a required parameter). The final request looks like this:

api.adegga.com/rest/v1.0/GetWineByAvin/AVIN6452997073019/&format=json&key=

You can test this right in your browser. You should see a long string of JSON data language. Note that the object returned is of resource type winelist. See section Resource Types for for details on this resource.

Sample request from PHP

Here is an example of a call in a PHP script. You can use any language that supports HTTP requests (JavaScript, Ruby, Perl, C#…) which is just about every language in use on the web.
$url = "api.adegga.com/rest/v1.0/GetWineByAvin/AVIN6452997073019/key=";
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response_body = curl_exec($ch);


Sample response

Here’s the response from our request above (with added white space to make it easier to read.) The response is formatted using JSON, a simple data serialization language that can be used by just about any language on the web. (To find JSON support for your language, go here.)


{
response:{
stat:'OK',
aml:{
version:1.0,
wines:{
count:1,
wine:[
{
avin:'AVIN1234567890123',
name:'My wine',
vintage:2005,
type:'White wine',
type_id:2,
country:'Spain',
country_id:724,
region:'Catalonia',
region_id:72407,
producer:'My Producer',
producer_id:123,
adegga_url:'http:\/\/www.adegga.com\/wine\/ AVIN1234567890123',
label_url:{}
}
]
},
legal:'By using this data you agree to the Adegga API terms of service.'
}
}
}


Notice the strange looking “\/” sequences are a side-effect of the JSON encoding, and will be converted to normal forward slashes when you decode the response data.

Sample Response in PHP

And here’s how we’d parse and use the response in PHP:

$response = json_decode($response_body);
$wine = $response->results[0];
print $wine->name."'s producer is: " . $wine->producer."\n";


Resource Types

Each command in the Adegga API will return objects of one of the following types:

* Country list- represent collection of countries.
* Winetype list – represents a collection of wine types.
* Producer list – represents a collection of producers.
* Wine list – represent a collection of wines.

Country list

Winetype list

Producer list

Wine list

Specific Site Info

Rating list

GetCountries

GetWineTypes

GetProducerByID

GetProducersByName

GetWineByAvin

GetWinesByName