From Open Knowledge Foundation

API for Caculators

Spec for code (python) library interface and associated web api (http://www.publicdomainworks.net/api/pd).

• See also: XML format spec

A first implementation of the api is running already at http://www.publicdomainworks.net/api/pd

To make a query to the api, please provide this information in JSON format:

• When: use it to calculate Public Domain for days other than today. i.e.: "1960'
• Jurisdiction: the country where you want to use the material, in ISO 3166. Currently we support 'uk'/'gb', 'us', 'ca'
• Work:
  • Title
  • Type: one of 'text', 'composition', 'photograph', 'law'
  • Date: Publication date
  • Creation date: if different than the edition you want to check
  • Persons: persons involved in this work (as authors, editors, translators, performers, producers...)
    • Name
    • Country: Country of birth in ISO 3166 format (important for some european calculations)
    • Type: person or organization (for legal documents, for example). If you have a birth and death date, then is obvious that the type of author is a person...
    • Birth/Death date: the most important part. If you just provide birth date, we will calculate 100 years later for death date. If you dont provide any, then we calculate the author as alive. It is also important to know, for some jurisdictions, if the author was alive at the time of publication.

Example

You can try the api with this example consult: [[{%22name%22%20:%20%22Boyle,%20James%22,%20%22type%22%20:%20%22person%22,%22birth_date%22%20:%20%2218490101%22,%22death_date%22%20:%20%22None%22,%22country%22:%20%22uk%22}}}|http://www.publicdomainworks.net/api/pd?q={"when": "20110101","jurisdiction":"uk","work": {"title": "Collected Papers on the Public Domain (ed)", "type": "text","date" : "19030101","creation_date" : "19030101","persons" : [{"name" : "Boyle, James", "type" : "person","birth_date" : "18490101","death_date" : "None","country": "uk"}]}}]]

Result

According with the information, you will receive a result with

• pd_probability value for Public Domain of the work
• Uncertainty: how clear is the situation, according with the information provided (more information, less uncertainty)
• log: the calculation process log
• input: your input to the api

#!python
class Work(object):
    title
    date # publication date
    creation_date
    persons # authors

class Entity(object):
    type = 'Human' # needed? (Govt data is special)
    name
    birth_date
    death_date
    country # 2 digit iso code

class PDCalcResult:
    def __init__(self):
        '''
        @param pd_probability: a float object representation probability it is
        in the public domain, with 1.0 = definitely PD, 0.0 = definitely not PD


        @param confidence:

        @param messages:
        '''
        self.pd_probability = None
        self.confidence = None
        self.messages = None
        self.decision_basis # needed?


import datetime
today = datetime.date.today()
def is_pd(work, jurisdiction, when=today):
    '''
    @param work: a Work object

    @param jurisdiction: a 2 digit iso code identifying jurisdiction we are
    calculation PD status for ...

    @param when: when we want to do calculation for (normally the present --
    but can be useful to work out what works will be PD next year or in 10
    years)

    @return: `PDCalcResult` object
    '''
    return PDCalcResult()