Artlogic Public Feeds API

Introduction

This page contains the 'Developers API' for the Artworks Feed mechanism from your Artlogic Management Platform to external websites if this mechanism has been turned on. Please contact support@artlogic.net if you would like to use this functionality.

Important information to read before you proceed: 

  • We do not offer technical support for this service. These feeds are very simple in structure, and should be easy to work with. 
  • You or your developer will be responsible for parsing the JSON feeds and updating your local database. 
  • You should not serve the feeds either directly or indirectly on a public web page (see our Terms and Conditions), as there are potentially hundreds of ways to do this depending on the platform on which your site is developed. 
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.

How to use the feeds

Feeds are available in the JSON. In the 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 JSON feeds from this server. Your script should connect to the feed URL and parse the resulting JSON data.

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.

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 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 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:

    • Artworks ('artworks')
      JSON Feed: https://feeds.artlogic.net/<account-name>/websites/2.0/artworks/json/ (demo)
    • Artwork Types ('artwork_types') - relates to 'artwork:type_id'
      JSON Feed: https://feeds.artlogic.net/<account-name>/websites/2.0/artwork_types/json/ (demo)
    • Artwork Categories ('artwork_categories') - relates to 'artwork:selected_categories' ('\r'-separated list)
      JSON Feed: https://feeds.artlogic.net/<account-name>/websites/2.0/artwork_categories/json/ (demo)
    • Artwork Periods ('artwork_periods') - relates to 'artwork:period_id'
      JSON Feed: https://feeds.artlogic.net/<account-name>/websites/2.0/artwork_periods/json/ (demo)
    • Currencies ('currencies') - relates to 'artwork:retail_currency'
      JSON Feed: https://feeds.artlogic.net/<account-name>/websites/2.0/currencies/json/ (demo)
    • Tax Codes ('tax_codes') - relates to 'artwork:tax_code'
      JSON Feed: https://feeds.artlogic.net/<account-name>/websites/2.0/tax_codes/json/ (demo)

Important Feed Information

  • 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. Our feed contains only Artwork details.
  • The JSON feed contains a link to an artwork image url: ‘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 shared 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 your website CMS and will not be exported from our systems .
  • Please note that there is a delay of up to thirty minutes between records being modified on the Database and being exported to the feed mechanism.

Feed Types/Namespaces

Artworks ('ARTWORKS')

Obviously, this is the most important of the feeds as it contains all the details of the artworks that have been set on Artlogic to be exported to the website. Most fields (id, artist, title, 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.

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 Artlogic instance:

  • 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 within Artlogic, 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.

Currencies ('CURRENCIES')

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. 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. 

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, specifically to be used on the website. If present it should be used in place of 'label'.

For further reading: If you require further information on JSON API, we suggest this reading available via Rapid. Click here to learn more.

Was this article helpful?
0 out of 0 found this helpful

Related articles