ESS Bibliography API documentation
Version: 0.1
Further Info: May Dousak (may.dousak@fdv.uni-lj.si)
--------------------------------------------------------------------------------
1. GENERAL PRINCIPLES
2. LIST OF CALLS
--------------------------------------------------------------------------------
1. GENERAL PRINCIPLES
1.1 SENDING REQUESTS
Your client should request queries using a POST parameter to:
a) API URL
default: https://bibliography.europeansocialsurvey.org/api
b) an appropriate command, passed as a POST variable w
c) (optional) parameters as additional POST variables
1.2 RECEIVING RESPONSES
In case of success, data is received along with HTTP code 200 ("OK").
In case of wrong call, http code 400 ("Invalid request") is returned.
In case of error in server side appropriate HTTP response code along with
text content is returned.
In essence: check the response codes before reporting bugs!
1.3 JQUERY CLIENT EXAMPLE
The following simple example requests the lists of countries and fills the
according drop-down ("affiliation").
$.ajax ({
method: "POST",
url: API_URL,
data: {
w: 'list_countries'
}
})
.done (function (msg) {
if (msg == '') {
console.log('No response received from API!');
}
else {
$('#affiliation').html('<option value="0">Any</option>');
if (msg['status'] == "200") {
msg['data'].forEach(function (item) {
$('#affiliation').html( $('#affiliation').html() + '<option value="' + item['id'] + '">' + item['name'] + '</option>');
});
}
else {
console.log(msg);
}
}
})
.fail (function() {
console.log('No response received from API!');
});
--------------------------------------------------------------------------------
2. LIST OF COMMANDS
browse
Displays list of entries based on the browse data
Extra POST variables:
(in progress. Please refer to classes/browse.php)
Response: json array of results.
browse2spreadsheet
Exports the current list of entries into a spreadsheet (CSV).
Extra POST variables:
(in progress. Please refer to classes/browse.php)
Response: CSV file.
display_item
Displays details for the selected item (from search_suggestions)
Extra POST variables:
id - id of the item
Response: array (
name : item name
label : item label
block : block item resides in
txt : item full text )
doi
Fetches bibliographic data from DOI record. Please use sparingly as it
connects to third-party servers (DOI) and we do not want to get blocked.
Extra post varialbes:
doi : doi record
Response: array containing citation data.
item2spreadsheet
Exports item citations into a spreadsheet
Extra POST variables:
id: item id
Response: CSV file.
item_citations
Displays all the bibliographic entries "using" the selected item.
Extra POST variables:
id: item id
Response: json list of entries using the given item.
list_countries
returns list of countries (for which there are bibliographic entries)
you might want to use in a form for searching records.
Extra POST variables: none
Response: array(country_id => country_name)
list_items
returns list of ESS items you might want to use in a form for searching
records.
Extra POST variables: none
Response: array(item_id => item_name)
list_journalField
returns list of journal fields you might want to use in a form for
searching records.
Extra POST variables: none
Response: array(journal_id => journal_name)
list_modules
returns list of ESS modules you might want to use in a form for
searching records.
Extra POST variables: none
Response: array(module_id => module_name)
list_pubType
returns list of all publication types you might want to use in a form
for searching records.
Extra POST variables: none
Response: array(pubType_id => pubType_name)
list_rounds
returns list of ESS rounds you might want to use in a form for
searching records.
Extra POST variables: none
Response: array(round_id => round_name)
list_topics
returns list of ESS topics countries you might want to use in a form for
searching records.
Extra POST variables: none
Response: array(topic_id => topic_name)
search
See search_suggestions.
When fulltext is enabled, it will return list of all results.
search_suggestions
returns list of search suggestions for fulltext search.
Currently, it only works on item search (need to update it to fulltext)
Extra POST variables:
txt - fulltext to search for
Response: array (
id : item ID
name : item name
label : item label
block : block item resides in
txt : item full text )
total_items_published
Returns the number of records in the database.
Extra POST variables: none
Response: number of bibliographic entries (integer).
