Introduction

This HTTP Key => Value API was setup to provide a sane way to access (meta) data of books in print in the Netherlands in a simple machine programmable way.

NB: a valid contact email-address has to be provided in every API call if you use it more then incidentally. This provides us a way of contacting you in case of any detected problems.

! Failure to provide a valid contact address in the header will lead to blocking of your IP/CIDR in case of heavy usage !

How to use the easycbapi API

It’s quite simple to use. Simply request :

https://easycbapi.nl/isbn/the-isbn-nummer

And it will output any information it has about this ISBN in a simple key:value format

Example: https://easycbapi.nl/isbn/9789083316642

Example using curl:

    
    shell> curl -s -H "contact: developer_to_contact@example.org" https://easycbapi.nl/isbn/9789002219788

    isbn:9789002219788
    title:Het generatiepact
    author:B. Huygebaert
    mutationlog:
    ProductSupply.SupplyDetail.Price.CurrencyCode:EUR
    ProductSupply.SupplyDetail.Price.PriceAmount:9.95
    ProductSupply.SupplyDetail.Price.PriceType:02
    ProductSupply.SupplyDetail.ProductAvailability:99
    CollateralDetail.TextContent.TextType:05
    DescriptiveDetail.Contributor.ContributorRole:A01
    DescriptiveDetail.Contributor.KeyNames:Huygebaert
    DescriptiveDetail.Contributor.NamesBeforeKey:B.
    DescriptiveDetail.Contributor.PersonName:B.  Huygebaert
    DescriptiveDetail.Contributor.SequenceNumber:1
    DescriptiveDetail.EditionNumber:1
    DescriptiveDetail.Extent.ExtentType:00
    DescriptiveDetail.Extent.ExtentUnit:03
    DescriptiveDetail.Extent.ExtentValue:168
    DescriptiveDetail.Illustrated:01
    DescriptiveDetail.Language.LanguageCode:dut
    DescriptiveDetail.Language.LanguageRole:01
    DescriptiveDetail.NoCollection: 
    DescriptiveDetail.ProductComposition:00
    DescriptiveDetail.ProductForm:BC
    etc.
    

To receive a list of all ISBN’s that have been changed since date X, use :

https://easycbapi.nl/isbn-since/20230901

The date has to be provided in the UNIX posix format ‘%Y%m%d’, meaning: fullyear, the number of the month and the number of the day.

Example of a valid date: 20230130

It can be generated with the Unix command:

    shell> date '+%Y%m%d'

    20230130

Or more likely with a strftime function or its derivatives:

    strftime("%Y%m%d", timestamp )

So a call to the /isbn-since/ api in curl can be :

    shell> curl -s -H "contact: developer_to_contact@example.org" https://easycbapi.nl/isbn-since/20230130

    9789083117614
    1789083117615
    8784803117617
    etc.

A note of warning: If for whatever reason we are out of sync with Centraal Boekhuis, and forced to do a completely new import, it will list ALL isbn’s as modified!

To get a list of all ISBN’s published use:

    shell> curl -s -H "contact: developer_to_contact@example.org" https://easycbapi.nl/isbn-since/all | wc -l 
    1986968

A simple, crude and inefficient way to use the api call’s combined would be :

    #!/bin/sh 

    # What date was the update last run? 
    DATE = `cat last_run_date.state`

    # fetch updated ISBNs since this date, and runs update_isbn with each changed ISBN
    curl -s -H "contact: developer_to_contact@example.org" https://easycbapi.nl/isbn-since/$DATE | xargs -r -i sh -c 'curl -s -H "contact: developer_to_contact@example.org" https://easycbapi.nl/isbn/{} | ./update_isbn {} '
    # ./update_isbn takes the first commandline arg as the name of the ISBN, and reads key:values from its STDIN.
    # how it updates the data in a database is implementation dependent and beyond this example

    # update the last_run_date.state state file
    date '+%Y%m%d' > last_run_date.state

    

This of course has no error checking, and is very inefficient, since it spawns a new process for every update but it shows how one could use the combined api’s, and is simple to read and understand.

Another example in which you update all of your book information:

    #!/bin/sh
    #
    # in this case you have a csv file that lists all isbn's your shop caries in the first field, and dump them to STDOUT with the cat books.csv  |awk -F, '{print $1}' 
        # the sed -e 's/"//' is there to strip away "" from "9789083117614" which some CSV exports put around any value.

    cat books.csv  |awk -F, '{print $1}' | sed -e 's/"//' | xargs -r -i sh -c 'curl -s -H "contact: developer_to_contact@example.org" https://easycbapi.nl/isbn/{} | ./update_isbn {}'

Resources

Resources of a ISBN such as book covers can also be fetched.

You can retrieve any cover / with the url:
https://easycbapi.nl/resources/jpg/(resource)

For example the resource links from ISBN 9789046828540 are:

    shell> curl -s https://easycbapi.nl/isbn/9789046828540| egrep 'jpg'

    CollateralDetail.SupportingResource.1.ResourceVersion.ResourceLink:9789046828540_VRK.jpg
    CollateralDetail.SupportingResource.2.ResourceVersion.ResourceLink:9789046828540_DVB.pdf
    CollateralDetail.SupportingResource.0.ResourceVersion.ResourceLink:9789046828540_ATK.jpg

And they can be fetched from :

https://easycbapi.nl/resources/jpg/9789046828540_VRK.jpg

https://easycbapi.nl/resources/jpg/9789046828540_ATK.jpg

To prevent hotlinking the referrer must either be empty, or the site itself.

In other words: if you simply fetch the resource everthing should be ok, but hotlinking won’t work.

Links

If you’re going to have to deal with the ONIX standard, you will need to read these links

Contact

Contact questions@easycbapi.nl if you have questions, experience problems, have remarks or because you feel like it.

Caveat: If you don’t understand the listed examples, this API is probably not for you.