Artlogic Public Feeds API
Version: 2.0 — firstname.lastname@example.org
This page contains the 'Developers API' for the Artworks Feed mechanism
from Artlogic Online
to external websites if this mechanism has been turned on. Please
contact Artlogic if you would
like to use this functionality. For more information about Artlogic Online,
The feeds are based on a standard RSS feed with additional functionality based on Yahoo's 'Media RSS feed' format (http://www.rssboard.org/media-rss). All 'fields' are available as elements within within a custom namespace, e.g. 'artwork:artist', 'artwork:title', 'artwork:year', etc.
You or your developer will be responsible for parsing the XML/JSON feeds and updating your local database - you should not serve the feeds either directly or indirectly on a public web page (see Terms and Conditions, below). As there are potentially hundreds of ways to do this depending on the platform in which your site is developed. We do not offer technical support for this service. A good developer should be able to work with these feeds without too much trouble as the feeds themselves are very simple in structure.
Please note: the API is subject to change without notice as we add more fields to the Artworks exports. We are extremely unlikely to remove fields however it is the developer's responsibility to check that the data you are expecting is actually present.
Records are not served in a specific order - you will be responsible for sorting records as you see fit. In some cases a 'sort' value will sort records into a user-defined order set within Artlogic Online.
Separate feeds are available for each 'table' or 'namespace', explained in detail below. The following list shows the types of feeds available, and examples of the feed URLs in the two available formats (xml and json). Note that you will need to insert your own gallery name (e.g. your Artlogic Online account name) in the appropriate place in the URL.
Where data is available, the 'demo' link will show you example feed pages using data from the Artlogic Online demonstration system. You may use these demo URLs to test your system before you are ready to go live of if you do not yet have any records in Artlogic Online:
Artwork Types ('artwork_types') - relates to 'artwork:type_id'
Artwork Categories ('artwork_categories') - relates to 'artwork:selected_categories' ('\r'-separated list)
Artwork Periods ('artwork_periods') - relates to 'artwork:period_id'
Currencies ('currencies') - relates to 'artwork:retail_currency'
Tax Codes ('tax_codes') - relates to 'artwork:tax_code'
There is no setup charge for the 'feeds' service. The service is
currently charged at £200.00 per
annum for up to 400 artworks, plus
£15.00 per annum for each additional
100 artworks thereafter, billed quarterly in arrears
(plus applicable taxes). Number of artworks is calculated based on the
highest number of artworks in any feed served during each month of the given
billing period, rounded up to the nearest 100.
If you prefer you may opt for a fixed unlimited artworks package priced at £500.00 per annum. Please note that we do not monitor the unlimited artworks per annum package so we won't be able to offer any refunds if you might have saved by being on a flexible tariff.
Prices do not include VAT which will be added if you are in the EU.
How to use the feeds
Feeds are available in two formats, XML or JSON. For the
purpose of this document we will generally discuss the XML feed format however the
format of the JSON feed is very simple and should be self-explanatory if you would
prefer to use it. In the the JSON feed, the 'feed_data' object contains information
about the feed page, including 'next' and 'previous' page links, and the 'rows'
object contains the records themselves.
You will need to develop your own scripts or server-side mechanisms to pick up the XML feeds from this server. Your script should connect to the feed URL and parse the resulting XML data. Each <item> element contains a record, and each element with names like the following <artwork:id>, <artwork:title>, <artwork_type:id>, <artwork_type:name> represents a field of the given type or namespace, explained on this page. Each 'field' will contain a 'value' attribute containing the field value.
Pagination: Maximum 100 records per page
Please note that each page will contain a maximum of 100 records. The elements <artwork:feeddata>, <artwork_types:feeddata>, etc. will tell you how many records (no_of_records) and pages (no_of_pages) are available. You will need to follow the <atom:link rel="previous" href="..." /> and <atom:link rel="next" href="..." /> links to retrieve the next or previous set of records, e.g.:
<atom:link rel="previous" href="http://127.0.0.1:5861/<account-name>/websites/2.0/artworks/xml/1"/>Equivalent 'previous' and 'next' urls are also provided in the JSON data feeds.
<atom:link rel="next" href="http://127.0.0.1:5861/<account-name>/websites/2.0/artworks/xml/3"/>
Terms & Conditions
How you use the information is up to you, however you should use the feed
to update a local database - or local pages. The feed itself must not be
served to the public either directly or indirectly. We will not explain how
to parse the data it into a database - your developer should be able to do this
with the help of the notes on this page.
Depending on the skill and competence of your developer and the format of your site, you may need to create artwork information and images separately for other sections of the site apart from artists/artworks - for instance Exhibitions and Artist pages. The Artlogic feed contains only Artwork details.
The XML feed contains a link to an artwork image url: 'artwork:img_url'. The image links should not be used directly on the website - you must download and process the images and serve them locally.
The feed should not be given out or used by anyone except your website developer and website mechanism.
You should not make more than one request for one page of the feed per second and you should not request the same page more than once every five minutes.
Only artworks and related tables (e.g. currencies, artwork types, etc.) are exported: artist biographies, publications, exhibitions, etc. should be built into the website CMS and will not be exported from Artlogic.
Please note that there is a delay of up to thirty minutes between records being modified on Artlogic Online and being exported to the feed mechanism.
Obviously, this is the most important of the feeds as it contains all the details of the artworks that have been set on Artlogic Online to be exported to the website. Most fields (artworks:id, artworks:artist, artworks:title, artworks:year, etc) are self-explanatory. Some fields, however, need some further explanation and these are explained below. Please note that the website feed only contains records that have specifically been set to export to the website, so it is safe to display any record included in the feed. Some fields may not be relevant to your particular site and instance of Artlogic Online.
Some fields, like 'artwork_html', 'artist_title_year' are HTML concatenations of other fields. 'artwork_html', for instance, is a very useful field for displaying the complete artwork details, fully formatted in HTML. Similarly, 'artwork_details_html' contains the medium and dimensions, etc., which may be useful if you want to display these separately from the artist name, title and year.
Some specific - and perhaps slightly unusual - fields are discussed below. Please note that some may not be relevant to your particular instance of Artlogic Online:
- additional_website_export_item — if this is set to 1, this record has been exported to the website feed but is not necessarily to be included in a list of browsable works by an artist. It may have been exported in order to add to an Exhibition record or for another reason.
- in_browsable_works — if '1', this item may certainly be included in the artist's 'browsable works'.
- in_artists_representative_works — if '1', this item may be included in a list of works representing the artist - a subset of all browsable works by this artist. Frequently, this might be used as a slide-show of works on an artist's page.
- is_artists_representative_work — if '1', this work should be considered the definitive work that represents the artist. Only one work by each artist will have this value selected.
- artists_representative_works_sort — an optional sort value for the list of works representing an artist. This field may not be used in your system.
- is_defining_work_in_categories — This field may contain a list of category IDs separated by '\r'. If so, this work is considered a defining work representing the given category (see 'artwork_categories'). A maximum of one work in the entire database will represent each category.
- represents_category — This field may contain a list of category IDs separated by '\r'. If so, this work represents the given categories for this artist. A separate field 'is_defining_work_in_categories' (see above) represents the category across the entire database.
- represents_period — This field may contain a list of artwork_period IDs separated by '\r'. If so, this work represents the given period for this artist.
- add_to_online_shop — if '1', this item has been set to be available for sale on the website.
- replace_artwork_detail_with_video — if '1' the artwork image should be replaced with the video embed code given in the '' field, if it exists.
- show_price_on_website — if '1', retail price details should not be displayed on the website. In fact, for obvious reasons, retail price information will not be available on the feed.
- details_override — if present, this html should replace the entire artwork details.
- video_embed_code — video embed code if the work is a video.
- img_url — The URL to the main artwork image. You must not use this URL directly on your website. Images must be imported if a change in the URL is detected and referenced from your own servers. If the image changes or is edited at Artlogic Online the image URL will always be different so you keep the same filename you need not worry about images being cached on end-user's browsers.
- img_urls_secondary_images — Additional URLs of images that have been set to appear on the website (e.g. artwork detail views, etc.).
Artwork Types ('artwork_types')
Artwork types may include, for example 'Painting', 'Sculpture', etc. It is possible to split sections of the website into these types. Artwork Types relate to artwork records though the 'type_id' field. The structure of the table is simple and should require no explanation - please see the demo feeds, above.
Artwork Categories ('artwork_categories')
Artwork categories, if used, may include, for example 'Painting', 'Sculpture', etc, like Artwork Types, however they could also include categories like 'Works under $1,000'. Once again, it is possible to split sections of the website into these categories. Artwork Categories relate to artwork records though the 'selected_categories' field which may contain multiple values (record IDs) separated by '\r'. The structure of the table is simple and should require no explanation - please see the demo feeds, above.
Artwork Periods ('artwork_periods')
Works like Artwork Categories but is used for artwork Periods, e.g. 'Cubism', 'Vorticism', etc. The values are stored in the same way as Artwork Categories — see above.
If retail prices are included in the feed (they may not be — see above), then the 'retail_currency' field in artwork records will contain a value relating to values in this table. Currencies may be edited by administrators in Artlogic Online. Fields are as follows:
- name — the currency as you would wish to display it on the website, e.g. '$' or '£'
- code — a code representing the currency (e.g. 'USD')
- local_currency — '1' if the currency is the local currency.
- default_currency — '1' if the currency is the default currency in Artlogic Online.
Tax Codes ('tax_codes')
Tax codes (e.g. 'Margin Scheme', 'Temporary Import', etc.) may not be used at all on the website, but if you wish to, they relate to artwork records through the 'tax_code' field. Fields are as follows:
- label — the tax code as you would wish to display it on the website.
- code — a short code representing the currency, where space is limited.
- label_on_website — an optional label which has been entered on Artlogic Online specifically to be used on the website. If present it should be used in place of 'label'.