Use of the API

 

To facilitate the reuse of data from the Callfront project, the website provides an API (Application Programming Interface (API)).

This API allows users to query, retrieve and download data from the Callfront website. It is based on the standard API provided by Omeka S, the content management system (CMS) on which Callfront has been developed.

Contents

API root URL

All API requests begin with the following base URL: https://callfront.inha.fr/api/

The API root URL provides access to the complete list of API resources available in the Callfront Omeka S instance.

From this entry point, you can browse the available endpoints (such as items, item_sets, media, properties, resource_classes, etc.) and build your own queries to retrieve data.

Building a simple query

To retrieve all available data (items and scripts), use the following endpoint:

https://callfront.inha.fr/api/items

Changing the number of returned items

By default, the API returns 100 items per request in JSON format.

You can increase this limit by using the per_page parameter. For example:

https://callfront.inha.fr/api/items?per_page=500

You may request any number of items, for example:

https://callfront.inha.fr/api/items?per_page=2000

Note: the larger the number of requested items, the longer the response may take to load.

Building an advanced query

General syntax

Advanced API queries must follow a specific syntax. Each search criterion is defined by three parameters:

  • property[0][property] → the search field indice
  • property[0][type] → the type of search to perform
  • the identifier (o:id) of the property to search
  • property[0][text] → the value to search for

The different parameters must be separated by ampersands (&):

property[0][property]={property ID}&property[0][type]={search type}&property[0][text]={search value}

Search parameters: search field indice, properties, types and values

To build a query, you must specify:

  • search field indice (property[0][xxxx]);
  • the type of search (property[0][type]);
  • the identifier (o:id) of the property to search (property);
  • the value to search for (text).

Search fields indice and properties

Do not confuse the search field indice, which is referred to as property[X] in the API syntax, with the property o:id code used in the query.

In Callfront, both items and scripts use the same resource template. The complete list of available properties and their corresponding identifiers (o:id) is available at:

https://callfront.inha.fr/api/properties?per_page=500

Note: by default, the API displays only the first 100 properties. Increase the per_page parameter to retrieve the complete list.

In addition to items and scripts, the Callfront project also defines Item Sets, representing geographical areas (countries, regions, etc.) grouping together objects originating from the same area.

For example:

  • geographical Item Sets contain a single search field indicating whether an object belongs to a given geographical area;
  • items also expose a single search field (item descriptor), which can target multiple properties.

Consequently, queries targeting geographical areas or items always use the search field indice property[0]. The number 0 refers to this unique search field.

Scripts, however, expose several search fields. Their indices must therefore be adjusted according to the search field in which you want to search for a given value associated with a given property : [1], [2], [3].

There is no API endpoint listing the available search field indices. The indice of a search field can be inferred either from its position in the search form or by examining the URL generated by the web interface after performing a search.

Search types

Each property can be queried using several search operators. Using the value "flower" as an example:

  • eq: exact match (returns only values equal to "flower", but not "flowers" or "flowering").
  • neq: exact non-match (returns values different from "flower").
  • in: contains (returns values containing "flower", such as "flowers" or "flowering").
  • nin: does not contain (returns values that do not contain "flower" in any form).
  • ex: property is not empty (returns all resources having at least one value for this property).
  • nex: property is empty (returns all resources with no value for this property).

Search value

Finally, specify the value to search for, for example: Hadith, alif vertical, rectangle, etc.

Building your query

You can now build your query by appending the search parameters to the API base URL.

For example, to retrieve all objects belonging to the geographical Item Set China:

https://callfront.inha.fr/api/items?item_set_id[]=2633&per_page=500

By default, only 100 results are returned. Increase the number of returned resources using the per_page parameter.

When querying Item Sets, there is no need to specify a field indice or a property because they expose only one search field. The identifier (o:id) of the geographical area is sufficient.

In this example, 2633 is the o:id corresponding to China.

The complete list of geographical Item Sets and their identifiers is available here.

Beyond Item Sets, you can of course query the API directly for items and scripts.

Example of a simple property query

https://callfront.inha.fr/api/items?property[0][property]={property ID}&property[0][type]={search type}&property[0][text]={search value}

Replacing the placeholders with actual values, the following query retrieves objects whose Text Type property (329) contains the value "Devotional text":

https://callfront.inha.fr/api/items?property[0][joiner]=and&property[0][property]=329&property[0][type]=in&property[0][text]=Devotional+text

Note: each parameter must be separated by an ampersand (&).

As previously explained, you can increase the number of returned resources by appending &per_page=500 (or another value) to the query.

Here is another example querying scripts rather than items:

https://callfront.inha.fr/api/items?property[1][joiner]=or&property[1][property]=266&property[1][type]=in&property[1][text]=rectangular

This query searches scripts whose General Characteristics search field (property[1]) contains the property Shape (266) with the value "rectangular".

Building a multi-criteria query with logical operators

You can build more advanced queries by combining several search criteria. For example, suppose you want to retrieve all items belonging to the geographical Item Set Greater Iran (1767), and whose Text Type property (329) contains the value Hadith, or whose scripts contains ascending alif vertical.

Each property[X] block represents one search criterion. The Boolean operator between two criteria is determined by the joiner parameter.

To achieve this, simply concatenate the different query parameters using ampersands (&):

item_set_id[]=1767
&property[0][joiner]=and
&property[0][property]=329
&property[0][type]=in
&property[0][text]=Hadith
&property[3][joiner]=or
&property[3][property]=240
&property[3][type]=in
&property[3][text]=alif+-+vertical

Since Ascender corresponds to the fourth search field available for scripts, its indice is property[3] (remember that indexing starts at 0).

You may combine as many search criteria as required, even between properties which are in the same field indice.

To combine multiple search criteria, use the joiner parameter: property[X][joiner]=and or property[X][joiner]=or

This parameter specifies the Boolean operator used to combine the current criterion with the previous one.

Remember that the Boolean operator between two criteria is defined by the joiner parameter of the current criterion. The first criterion usually has joiner=and, but this has no practical effect because there is no previous criterion.

Understanding the query results (converting JSON to CSV)

The results of your query are returned in JSON format, which is not always easy to read or analyse directly.

If you would like to view the results in a spreadsheet application, you can convert the JSON output into CSV format using an online converter:

https://www.convertcsv.com/json-to-csv.htm

Simply copy the entire JSON response returned by the API and paste it into the converter, in the "Step 1: Select your input → Enter Data" field.

Then click "Convert JSON to CSV".

Once the conversion is complete, click "Download Result" to download the CSV file, which can be opened in any spreadsheet software.