Art & Antique News Online - Our API

Our API

You can use our API to integrate our feeds into your own applications. We currently have libraries written for PHP and Perl to help you do this, but you can easily use the documentation below to create a library in your language of choice (if you do, why not send it to us so we can share it on these pages? Email us your solutions).

How to access our data
Authentication
Fetching data
Pre-written libs
1. Perl
2. PHP

1. How to access our data

We provide all of our data in XML, with our story search results coming back in RSS. You can access our data by querying the following url:

http://news.cinoa.org/news.pl

2. Authentication

To put it simply, there is none! The only bit of information you can give us is an optional program name:

http://news.cinoa.org/news.pl?program_name=MyAppv1.0;

Simple as that.

3. Fetching data

All of our data is provided in XML. You can make requests for certain types of data by querying our url (http://news.cinoa.org/news.pl) with your request simply attached as parameters in the url.

3.1 Available Languages

Our news sources are available in a number of languages, you can find out what languages we currently have available by setting the action parameter in the url to "fetch_langs":

http://news.cinoa.org/news.pl?action=fetch_langs;

3.2 Available Categories

We automatically categorise any news story that we find. To get a list of our current categories simply set the action parameter in the url to "fetch_categories":

http://news.cinoa.org/news.pl?action=fetch_categories;

You can optionally pass in a language code to retrieve the categories in a specific language (the language code needs to be one of our available languages, see 3.1):

http://news.cinoa.org/news.pl?action=fetch_categories;lang=fr;

3.3 Sources

We syndicate a number of Art and Antiques news websites in order to provide you with links to their newest sources all in once place. If you wish to view which sources we are currently syndicating simply set the action parameter in your request url to "fetch_sources":

http://news.cinoa.org/news.pl?action=fetch_sources;

3.4 Search constraint options

When you want to carry out a story search you will need to know what are valid options for each of the parameters you can set. We provide you with a method to retrieve our latest list of supported options for Date constraints, Ordering of results and the number of results you can ask to be returned.

3.4.1 Date constraints

To fetch a list of the date constraints you can give in your story search requests, simply change the action parameter in your request url to "fetch_date_options":

http://news.cinoa.org/news.pl?action=fetch_date_options;

3.4.2 Results ordering

To fetch a list of supported orderings for your results, again change the action parameter in your request url to "fetch_order_options":

http://news.cinoa.org/news.pl?action=fetch_order_options;

3.4.3 Result limits

To fetch a list of supported limits for your story search request, change the action parameter in your request url to "fetch_limit_options":

http://news.cinoa.org/news.pl?action=fetch_limit_options;

3.5 Stories

Its time to put together everything above, and to craft your own story search requests. To carry out a search set the action parameter to "search" in your request url.

http://news.cinoa.org/news.pl?action=search;

Supported parameters:

lang
feed
cat
when
keywords
order
limit

Lang

The lang parameter lets you specify which language you wish to constrain your search to. The lang parameter needs to be one of the available language codes (see 3.1 above).

http://news.cinoa.org/news.pl?action=search;lang=fr;

Feed

The feed parameter lets you request stories from only 1 source. The feed parameter needs to be set to one of the source ids (see 3.3 above) in order to function correctly.

http://news.cinoa.org/news.pl?action=search;feed=11;

Cat

The cat parameter allows you to constrain your story results by 1 category, the cat parameter needs to be one of the available category ids (see 3.2) in order to function correctly.

http://news.cinoa.org/news.pl?action=search;cat=1;

When

The when parameter is a date constraint, and needs to be passed one of the date constraints given by our system using the method in part 3.4.1.

http://news.cinoa.org/news.pl?action=search;when=-2weeks;

Keywords

The keywords parameter can be used to search for stories matching a particular set of keywords:

http://news.cinoa.org/news.pl?action=search;keywords=new%20york;

Order

The order parameter allows you to modify the order in which your stories are returned, and needs to be given one of the ordering codes from part 3.4.2

http://news.cinoa.org/news.pl?action=search;order=views;

Limit

The limit parameter allows you to specify how many results you wish to return, and needs to be a value from our limiting values in part 3.4.3.

http://news.cinoa.org/news.pl?action=search;limit=20;

Putting it all together

You can string any number of these parameters above together to generate your own custom Art & Antiques feed! If you sign up for an account you can use your user area to create, save and modify your own personal feeds using exactly the same parameters as above.

4. Pre-written libs

4.1 Perl

To download our Perl solution (it includes all documentation and an example program), click here.

4.2 PHP

To download our PHP solution (it includes all documentation and an example program), click here.

Contents