Constitute Services

Overview

Making a Service Request

Service Method Specifications

Requesting lists of objects

constitutions

topics

locations

Topic searches

constopicsearch

sectionstopicsearch

Free-text searches

textsearch

Requesting constitution HTML

html

 

Overview

The Constitute Project site’s service methods enable developers to retrieve constitution and topic data. This document describes the services and how to use them.

Making a Service Request

To submit a service request send an HTTP GET request with a set of optional parameters. The parameters are included in the request URL as a set of name=value pairs. The service URL format is shown below.

https://www.constituteproject.org/service/<method_name>

[?<parameter_name>=<parameter_value>&<parameter_name>=<parameter_value>]

All service methods return JSON strings. Service methods are organised into categories as follows:

Constitution data, apart from constitution HTML, are returned in two forms: header data, and section data.  Methods returning header data are:

Methods returning constitution section data are:

Service Method Specifications

Requesting lists of objects


constitutions

Returns header data for constitutions. Optional region, country, and date-range filters are available.

Parameters

region

An optional region ID.  See the locations method below.  Only constitutions of the countries of the specified region are included in the search results. Multiple regions can be specified by repeating the region parameter.

country

An optional country ID.  See the locations method below. Only constitutions belonging to the specified country are included in the search results. Multiple countries can be specified by repeating the country parameter.

from_year

An optional first date-enacted year of a date range in YYYY format. If absent, the default is the earliest date-enacted. Only constitutions with a date-enacted year equal to or greater than  the from_year are included in the search results.

to_year

An optional last date-enacted year of a date range in YYYY format. If absent,  the default is the most recent date-enacted year. Only constitutions with a date-enacted year equal to or less than  the to_year are included in the search results.

lang

Optional parameter defining the language in which constitution titles are returned. The value of the parameter is a two-letter ISO 639-1 code. Currently supported values are en (English) and ar (Arabic). The default value is en.Only constitutions translated into the specified language will be returned.

historic

An optional Boolean value where true includes historic constitutions in the list and false excludes constitutions. Without this parameter historic constitutions are excluded.

Sample requests

Basic request without parameters:

https://www.constituteproject.org/service/constitutions

Request with region:

https://www.constituteproject.org/service/constitutions?region=Africa

Request with multiple regions:

https://www.constituteproject.org/service/constitutions?region=Africa&region=Europe

Request with a country:

https://www.constituteproject.org/service/constitutions?country=Ukraine

Request with date range:

https://www.constituteproject.org/service/constitutions?from_year=1954&to_year=2000

Request with region and from date:

https://www.constituteproject.org/service/constitutions?region=Europe&from_year=1960

Request with language specified:

https://www.constituteproject.org/service/constitutions?lang=en

Request to include historic constitutions:

https://www.constituteproject.org/service/constitutions?historic=false

Response format

[

    {

        country: <country_name>,

        id: <constitution_id>,

        in_force: true|false,

        title: <constitution_title>,

        year_enacted: <year_enacted>

    },

    …

    {

        country: <country_name>,

        id: <constitution_id>,

        in_force: true|false,

        title: <constitution_title>,

        year_enacted: <year_enacted>

    }

]

where:

country

The name of a constitution’s country

id

A constitution’s ID. Used as a parameter for calls on the sectionstopicsearch, textsearch, and html services

in_force

true if the constitution is in force otherwise false. If false the constitution is historic.

title

The title of a constitution. The title will be returned in the language defined by the lang URL parameter. If the language parameter is undefined then the constitution title’s language will default to English.

year_enacted

The year a constitution was enacted in YYYY format

An empty list [] is returned if no constitutions match the URL parameter values.

Sample response fragment (English titles)

[

    {

        country: "Afghanistan",

        id: "Afghanistan_2004",

        in_force: true,

        title: "Afghanistan 2004",

        year_enacted: "2004"

    },

    {

        country: "Albania",

        id: "Albania_2008",

        in_force: true,

        title: "Albania 1998 (rev. 2008)",

        year_enacted: "1998"

    },

Sample response fragment (Arabic titles)

[

    {

        country: "Argentina",

        id: "Argentina_194",

        in_force: true,

        title: "الأرجنتين 1853 (أعيد تفعيله 1983، المعدل 1994)",

        year_enacted: "1853"

    },


topics

Returns the complete topic hierarchy. Topics are organised in a hierarchy as follows:

<category_topic>

[<sub_category_topic>]

<topic>

<topic>

Note that the sub_category_topic level is optional. This means that category topics are either two or three levels deep.

Parameters

lang

Optional parameter defining the language in which topic description and label field values are returned. The value of the parameter is a two-letter ISO 639-1 code. Currently supported values are en (English) and ar (Arabic). The default value is en.

Sample request

https://www.constituteproject.org/service/topics?lang=en

Response format

[

    {

        description: <topic_description>,

        key: <topic_key>,

        keywords: [

            <keyword>,

            …

            <keyword>

        ],

        label: <topic_label>,

        topics: [

            {

                description: <topic_description>,

                key: <topic_key>,

                keywords: [

                   

                ],

                label: <topic_label>

                topics: [

                    {

                        description: <topic_description>,

                        key: <topic_key>,

                        keywords: [],

                        label: <topic_label>

                    },

                   

                ]

            },

           

        ]

    },

 

where:

description

A short description of the topic. The value is null if no description is available. The description will be returned in the language defined by the lang URL parameter. If the language parameter is undefined then the description language will default to English.

key

A topic key is a single short-form code

keywords

An optional list of synonyms of a topic key. May be empty.

label

The human-readable form of a topic. The label will be returned in the language defined by the lang URL parameter. If the language parameter is undefined then the description language will default to English.

topics

Depending on the hierarchy either a sub-category topic or a list of terminal topics

Sample response fragment

[

    {

        description: null,

        key: "amendment",

        keywords: [

           

        ],

        label: "Amendment",

        topics: [

            {

                description: "Details the way in which the text of the constitution can be formally amended. This is distinct from the task of constitutional interpretation often undertaken by courts.",

                key: "amend",

                keywords: [],

                label: "Constitution amendment procedure"

            },

            {

                description: "Some provisions in the constitutions may be so fundamental to the constitutional order, or so politically contentious, that they are designated as unamendable. In such cases, unamendable provisions are expressly noted in the constitution.",

                key: "unamend",

                keywords: [

                    "derogable",

                    "inalienable",

                    "inviolable"

                ],

                label: "Unamendable provisions"

            }

        ]

    },

    {

        description: null,

        key: "culture_and_identity",

        keywords: [

           

        ],

        label: "Culture and Identity",

        topics: [

            {

                description: null,

                key: "Citizenship",

                keywords: [],

                label: "Citizenship",

                topics: [

                    {

                        description: "Clarifies the citizenship status of members of indigenous groups. In some cases indigenous groups may be granted citizenship in a sub-national unit.",

                        key: "citdep",

                        keywords: [],

                        label: "Right of government to deport citizens"

                    },

                    {

                        description: "Describes the conditions under which a government is allowed to revoke an individual's citizenship. Some constitutions expressly forbid the government from revoking citizenship, regardless of the circumstances.",

                        key: "citizen",

                        keywords: [

                            "nationals",

                            "subjects"

                        ],

                        label: "Requirements for birthright citizenship"

                    },

This sample demonstrates a category topic without a sub-category topic (Amendment) and a category topic with a sub-category topic (Culture and Identity : Citizenship).


locations


Parameters

lang

Optional parameter defining the language in which country and region  name field values are returned. The value of the parameter is a two-letter ISO 639-1 code. Currently supported values are en (English) and ar (Arabic). The default value is en.

Sample request

https://www.constituteproject.org/service/locations?lang=en

Response format

[

    {

        countries: [

            {

                id: <country_id>,

                name: <country_name>

            },

          …

            {

                id: "<country_id>",

                name: <country_name>

            }

        ],

        id: <region_id>,

        name: <region_name>

    },

    {

        countries: [

          …

        ]

…            

where:

countries

A list of country dictionaries each containing a country ID and country name.

countries/id

A country ID. Used as a value on the country parameter of topic search methods.

countries/name

A country name. The country name will be returned in the language defined by the lang URL parameter. If the language parameter is undefined then the country name’s language will default to English.

id

A region ID. Used as a value on the region parameter of topic search methods.

name

A region name. The region name will be returned in the language defined by the lang URL parameter. If the language parameter is undefined then the region name’s language will default to English.

Sample response fragment

[

    {

        countries: [

            {

                id: "Algeria",

                name: "Algeria"

            },

           …

            {

                id: "Zimbabwe",

                name: "Zimbabwe"

            }

        ],

        id: "Africa",

        name: "Africa"

    },

    {

        countries: [

            {

                id: "Antigua_and_Barbuda",

                name: "Antigua and Barbuda"

            },

           …

            {

                id: "Venezuela",

                name: "Venezuela (Bolivarian Republic of)"

            }

        ],

        id: "Americas",

        name: "Americas"

    },

    {

        countries: [

            {

                id: "Afghanistan",

                name: "Afghanistan"

            },

…            

Topic searches


constopicsearch


Returns constitution headers for those constitutions that contain sections tagged by a topic.  Region, country, and date-range filters are available.

Parameters

key

A topic key, i.e. a topic’s short-form code. Only constitutions tagged with the topic are included in the search results.

region

An optional region ID.  See the locations method above.  Only constitutions of the countries of the region are included in the search results. Multiple regions can be specified by repeating the region parameter.

country

An optional country ID.  See the locations method above. Only constitutions belonging to the country are included in the search results. Multiple countries can be specified by repeating the country parameter.

from_year

An optional first date-enacted year of a date range in YYYY format. If absent, the default is the earliest date-enacted. Only constitutions with a date-enacted year equal to or greater than  the from_year are included in the search results.

to_year

An optional last date-enacted year of a date range in YYYY format. If absent, the default is the most recent date-enacted year. Only constitutions with a date-enacted year equal to or less than  the to_year are included in the search results.

lang

Optional parameter defining the language in which constitution titles are returned. The value of the parameter is a two-letter ISO 639-1 code. Currently supported values are en (English) and ar (Arabic). The default value is en.Only constitutions translated into the specified language will be returned.

historic

An optional Boolean value where true includes historic constitutions in the list and false excludes constitutions. Without this parameter historic constitutions are excluded.

Sample requests

Basic topic search with language parameter:

https://www.constituteproject.org/service/constopicsearch?key=amend&lang=en

Topic search with region:

https://www.constituteproject.org/service/constopicsearch?key=amend&region=Africa

Topic search with multiple regions:

https://www.constituteproject.org/service/constopicsearch?key=amend&region=Africa&region=Europe

Topic search with country:

https://www.constituteproject.org/service/constopicsearch?key=amend&country=Ukraine

Topic search with date range:

https://www.constituteproject.org/service/constopicsearch?key=amend&from_year=1954&to_year=2000

Topic search with request to include historic constitutions:

https://www.constituteproject.org/service/constopicsearch?key=amend&historic=true

Response format

See constitutions method section. If no constitutions match the values of the parameters then the constitutions list is empty.

Sample response

See constitutions method section


sectionstopicsearch


Returns all the sections tagged with a topic within a single constitution.  Note that the region, country, from_date, to_date,and  historic parameters will be ignored.

Parameters

key

A topic key, i.e. a topic’s short-form code. Only constitutions tagged with the topic are included in the search results.

cons_id

A constitution ID

lang

Optional parameter defining the language in which constitution sections are returned. The value of the parameter is a two-letter ISO 639-1 code. Currently supported values are en (English) and ar (Arabic). The default value is en.If the constitution defined by cons_id is not translated into the target language a 404 is returned.

Sample request

https://www.constituteproject.org/service/sectionstopicsearch?key=amend&cons_id=Afghanistan_2004&lang=en

Response format

The data structure is an array of section dictionaries where each section dictionary comprises:

additional

An array of  section dictionaries providing the context to the main section. May contain an items array defining sections that are list items.

cons_id

A constitution ID

context_index

Reserved - currently null

header

A section’s header which may be empty. The header will be returned in the language defined by the lang URL parameter. If the language parameter is undefined then the title’s language will default to English.

header_parts

An array of header parts that, when combined from array index order, are used to generate a section’s full header path. The text will be returned in the language defined by the lang URL parameter. If the language parameter is undefined then the text’s language will default to English.

id

A section ID defined in the constitution’s RDF

text

The section’s text which may be null. The text will be returned in the language defined by the lang URL parameter. If the language parameter is undefined then the text’s language will default to English.

topics

An array of topic keys for the topics used to tag a section

type

The type of section. One of:  title | body | olist | ulist

The array of section dictionaries is followed by the constitution’s long and short titles.

 

title

A constitution’s title. The title will be returned in the language defined by the lang URL parameter. If the language parameter is undefined then the title’s language will default to English.

title_short

A constitution’s short title. The short title will be returned in the language defined by the lang URL parameter. If the language parameter is undefined then the title’s language will default to English.

{

    sections: [

        {

            additional: [

                {

                    cons_id: <constitution_id>,

                    header: <section_header_text>,

                    header_parts: [

                        <header_part_text>,

                        …

                    ],

                    id: <section_id>,

                    text: <section_text>,

                    topics: [

                        <topic_key>,

                        …

                    ],

                    type: <section_type>

                },

               …

            ],

            cons_id: <constitution_id>,

            header: <section_header_text>,

            header_parts: [

                <header_part_text>,

                …

            ],

            id: <section_id>,

            text: <section_text>,

            topics: [

                <topic_key>,

                …

            ],

            type: <section_type>

        }

    ],

    title: <constitution_title>,

    title_short: <constitution_short_title>

}

An empty array []is returned for the following conditions:

Sample response fragment

A response to a search for the hogterm topic key with a country filter specifying China.

https://www.constituteproject.org/service/sectionstopicsearch?key=hogterm&cons_id=China_2004&lang=en

{

    sections: [

        {

            additional: [

                {

                    ancestor_sections: [],

                    cons_id: "China_2004",

                    context_index: null,

                    header: "",

                    header_parts: [

                        "CHAPTER III",

                        "Section 3",

                        "Article 87",

                        ""

                    ],

                    id: 364,

                    text: "The term of office of the State Council is the same as that of the National People's Congress.",

                    topic_children: [],

                    topics: [

                        "hogterml",

                        "execnum",

                        "hogterm",

                        "cabinet"

                    ],

                    type: "body"

                },

                {

                    ancestor_sections: [],

                    cons_id: "China_2004",

                    context_index: null,

                    header: "",

                    header_parts: [

                        "CHAPTER III",

                        "Section 3",

                        "Article 87",

                        ""

                    ],

                    id: 365,

                    text: "The Premier, Vice-Premiers and State Councilors shall serve no more than two consecutive terms.",

                    topic_children: [],

                    topics: [

                        "hogterml",

                        "execnum",

                        "hogterm",

                        "cabinet"

                    ],

                    type: "body"

                }

            ],

            cons_id: "China_2004",

            context_index: null,

            header: "Article 87",

            header_parts: [

                "CHAPTER III",

                "Section 3",

                "Article 87"

            ],

            id: 363,

            text: null,

            topics: [

                "hogterml",

                "execnum",

                "hogterm",

                "cabinet"

            ],

            type: "title"

        }

    ],

    title: "China 1982 (rev. 2004)",

    title_short: "China"

}

A response to a search for the cabsel topic key with a country filter specifying Australia.

https://www.constituteproject.org/service/sectionstopicsearch?key=cabsel&cons_id=Australia_1985&lang=ar

{

    sections: [

        {

            additional: [

                {

                    ancestor_sections: [],

                    cons_id: "Australia_1985",

                    context_index: null,

                    header: "",

                    header_parts: [

                        "الفصل الثاني",

                        "62",

                        ""

                    ],

                    id: 307,

                    text: "يجب أن يكون ثمة مجلس تنفيذي اتحادي لتقديم المشورة للحاكم العام في حكومة الكومنولث، وينبغي أن يختار الحاكم العام أعضاء هذا المجلس ويستدعيهم، كما أنهم يؤدون اليمين كمستشارين تنفيذيين ويشغلون مناصبهم في خلال ولايته.",

                    topic_children: [],

                    topics: [

                        "cabsel",

                        "cabdiss",

                        "cabinet"

                    ],

                    type: "body"

                }

            ],

            cons_id: "Australia_1985",

            context_index: null,

            header: "62",

            header_parts: [

                "الفصل الثاني",

                "62"

            ],

            id: 306,

            text: "المجلس التنفيذي الاتحادي",

            topics: [

                "cabsel",

                "cabdiss",

                "cabinet"

            ],

            type: "title"

        },

        {

            cons_id: "Australia_1985",

            context_index: null,

            header: "",

            header_parts: [

                "الفصل الثاني",

                "64",

                ""

            ],

            id: 311,

            text: "يجوز للحاكم العام تعيين موظفين عموميين لإدارة إدارات دولة الكومنولث كما يحدّده الحاكم العام في المجلس.",

            topics: [

                "cabsel",

                "cabpow",

                "cabinet"

            ],

            type: "body"

        }

    ],

    title: "أستراليا 1901 (المعدل 1985)",

    title_short: "أستراليا"

}

Note that the response contains elements marked in red. These are for internal use and, for this reason, are not documented above.

Free-text searches


textsearch


Returns constitution headers for constitutions with sections that contain the free-text search term. Region, country and date range filters are available.  Alternatively, can be used with the cons_id parameter to return a single constitution’s sections. If no constitution headers or sections are found then the result is an empty array [].

Parameters

q

A free-text search term. Only constitutions containing the text are included in the search results.

region

An optional region ID.  See the locations method above.  Only constitutions of the countries of the region are included in the search results. Multiple regions can be specified by repeating the region parameter.

country

An optional country ID.  See the locations method above. Only constitutions belonging to the country are included in the search results. Multiple countries can be specified by repeating the country parameter.

from_year

An optional first date-enacted year of a date range in YYYY format. If absent the default is the earliest date-enacted. Only constitutions with a date-enacted year equal to or greater than  the from_year are included in the search results.

to_year

An optional last date-enacted year of a date range in YYYY format. If absent the default is the current year. Only constitutions with a date-enacted year equal to or less than  the to_year are included in the search results.

lang

Optional parameter defining the language in which constitution sections are returned. The value of the parameter is a two-letter ISO 639-1 code. Currently supported values are en (English) and ar (Arabic). The default value is en.Only constitutions translated into the specified language will be returned.

historic

An optional Boolean value where true includes historic constitutions in the list and false excludes constitutions. Without this parameter historic constitutions are excluded.

or

q

A free-text search term. Only constitutions containing the text are included in the search results.

cons_id

A constitution ID

lang

Optional parameter defining the language in which constitution sections are returned. The value of the parameter is a two-letter ISO 639-1 code. Currently supported values are en (English) and ar (Arabic). The default value is en. If the constitution by cons_id  is not translated into the target language a 404 is returned.

historic

An optional Boolean value where true includes historic constitutions in the list and false excludes constitutions. Without this parameter historic constitutions are excluded.

Sample request

To return constitution headers for a set of constitutions:

https://www.constituteproject.org/service/textsearch?q=president&lang=en

To return sections of a single constitution:

https://www.constituteproject.org/service/textsearch?q=president&cons_id=Afghanistan_2004

Response format

For a response to a request for constitution headers see:  constitutions

For a response to a request for a single constitutions sections see: sectionstopicsearch

Sample response

For a response to a request for constitution headers see:  constitutions

For a response to a request for a single constitutions sections see: sectionstopicsearch

Requesting constitution HTML


html


Parameters

lang

Optional parameter defining the language in which constitution sections are returned. The value of the parameter is a two-letter ISO 639-1 code. Currently supported values are en (English) and ar (Arabic). The default value is en. If the constitution by cons_id  is not translated into the target language a 404 is returned.

Sample request

https://www.constituteproject.org/service/html?cons_id=Australia_1985&lang=en

https://www.constituteproject.org/service/html?cons_id=Australia_1985&lang=ar

Response format

{

        html: <constitution_html>    

}

where:

html

A constitution in HTML format

Sample response fragment in English

{

  • html: "<h1>Afghanistan 2004</h1> <section id="1" class="article-list level0 article-title"> <h2 class="float-left">Preamble</h2> <a href="#1" class="float-right article-share-link">Share</a> <section id="2" class="article-list level1 article-body"> <p>In the name of Allah, the Most Beneficent, the Most Merciful</p> </section> <section id="3" class="article-list level1 article-body"> <p>Praise be to Allah, the Cherisher and Sustainer of Worlds; and Praise and Peace be upon Mohammad, His Last Messenger and his disciples and followers</p>…

Sample response fragment in Arabic

{

  • html: " <h1>أستراليا 1901 (المعدل 1985)</h1> <p class="translator">ترجمة المؤسسة الدولية للديمقراطية والانتخابات</p> <section data-id="1" class="article-list level0 article-title"> <h2 id="1" class="float-left">الفصل الأول. البرلمان</h2> <section data-id="2" class="article-list level1 article-title"> <h3 id="2" class="float-left">الجزء الأول. الشؤون العامة</h3> <section data-id="3" class="article-list level2 article-title"> <h3 id="3" class="float-left">1. السلطة التشريعية</h3> <a href="#3" class="float-right article-share-link">Share</a> <section data-id="4"…