AGROVOC Data Access
Currently, there are three distinct ways to access AGROVOC data without the need of a UI:
SPARQL endpoint
http://agrovoc.uniroma2.it/sparql
SKOSMOS REST APIs
SKOSMOS provides a set of REST APIs to access its vocabulary data. The official AGROVOC SKOSMOS deployment can be accessed here. Using this REST APIs, it is possible, among other things, to search for concepts through its labels, filters such searches using specific languages (in the search term or even in the returned data) and then get all the information of a given concepts.
Here are a couple of examples on these REST APIs:
- Search all concepts having a label in English (en) starting with the word “bea”: http://agrovoc.uniroma2.it/agrovoc/rest/v1/search/?query=bea*&lang=en
- Search all concepts having a label in English (en) containing the word “bea”: http://agrovoc.uniroma2.it/agrovoc/rest/v1/search/?query=*bea*&lang=en
- Getting all data associated to the concept http://aims.fao.org/aos/agrovoc/c_3077 : http://agrovoc.uniroma2.it/agrovoc/rest/v1/data/?uri=http://aims.fao.org/aos/agrovoc/c_3077
To have the complete list of REST APIs available, please refer to the official guide .
Legacy Web Services (using SOAP protocol)
AGROVOC Web Services allow access to AGROVOC contents through SOAP Web Services technology. The current implementation of AGROVOC Web Services is fed by data from the RDF version of AGROVOC (currently, the master version being edited through VocBench).
The WSDL file for the Web Services is located here: http://agrovoc.uniroma2.it:8080/SKOSWS/services/SKOSWS?wsdl. A list of the currently implemented AGROVOC Web Services is provided below, together with their description.
A discussion group is available for asking specific questions about the AGROVOC Web Services.
AGROVOC can also be accessed through SPARQL. Check the AGROVOC Release page for getting to the SPARQL endpoint.
Note: the AGROVOC Web Services are fed by the Linked Open Data (LOD) version of AGROVOC (see Releases), which include also triples related to:
- the ontology vocabulary Agrontology,
- the mappings,
- trivially inferred triples produced automatically etc.
SOAP Web Services List
The following Web Services have been implemented to facilitate access to AGROVOC content through dedicated SOAP clients.
getConceptByKeyword
- getConceptByKeyword2
searchByModeLangScopeXML
simpleSearchByMode2
getConceptInfoByTermcode
getConceptInfoByURI
getDefinitions
getAllLabelsByTermcode2
getTermByLanguage
- getURIByTermAndLangXML
- getFullAuthority
- getConceptByURI
- getConceptByRelationshipValue
- getlatestUpdates
- getTermcodeByTermAndLangXML
- getTermExpansion
- getReleaseDate
- getWebServicesVersion
We do not plan to add further web services in the future, and recommend instead access to AGROVOC through the current SPARQL endpoint. (Since it is a "simple" SPARQL endpoint, to be used inside a browser, a site providing a UI is needed, for example: http://yasgui.org/ ).
SOAP Web Services Description
Here follows a list of the web services currently available for AGROVOC:
getConceptByKeyword
|
| |
Name of Web Service | getConceptByKeyword(String ontologyName, String searchString, String format, String searchMode, String lang) | |
Description | This service will search for a concept by means of the input searchString, and then return its description. The search can be filtered through the specified searchMode and language lang. The result of this method will be in TXT or SKOS format. | |
Parameters | String ontologyName String searchString String format : TXT, SKOS, URI-txt String searchMode (contains, exact match, starts with, ends with, exact word) String lang | |
Return Values | String result | It return the concept by a given keyword, search mode and language |
Example | ontologyName:Agrovoc searchString:Acquired characters format:SKOS searchMode:Exact Match lang:en
Output: <?xml version="1.0" encoding="utf-8"?> <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:skos="http://www.w3.org/2004/02/skos/core#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:foaf="http://xmlns.com/foaf/0.1/" xmlns:aos="http://aims.fao.org/aos/common/" > <skos:Concept rdf:about="http://aims.fao.org/aos/agrovoc/c_99"> <skos:prefLabel xml:lang="ar">صفات مكتسبة</skos:prefLabel> <skos:prefLabel xml:lang="cs">získané vlastnosti</skos:prefLabel> <skos:prefLabel xml:lang="de">ERWORBENE EIGENSCHAFT</skos:prefLabel> <skos:prefLabel xml:lang="en">Acquired characters</skos:prefLabel> <skos:prefLabel xml:lang="es">Caracteres adquiridos</skos:prefLabel> <skos:prefLabel xml:lang="fa">نشانویژگیهای اکتسابی</skos:prefLabel> <skos:prefLabel xml:lang="fr">Caractère acquis</skos:prefLabel> <skos:prefLabel xml:lang="hi">उपार्जित लक्षण</skos:prefLabel> ……………………
| |
getConceptByKeyword2
|
| |
Name of Web Service | getConceptByKeyword2(String ontologyName, String searchString, String format, String searchMode, String lang, String outlang) | |
Description | This service will search for a concept by means of the input searchString, and then return its description. The search can be filtered through the specified searchMode and language lang. The result of this method will be in TXT or SKOS format. | |
Parameters | String ontologyName String searchString String format String searchMode (contains, exact match, starts with, ends with, exact word) String lang String outlang (it is used to filter the results obtained using the other input parameters)
| |
Return Values | String result | It return the concept by a given keyword, search mode and language filtered using the outlang input parameter |
Example | ontologyName:Agrovoc searchString:Acquired characters format:SKOS searchMode:Exact Match lang:en outlang:en
Output: <?xml version="1.0" encoding="utf-8"?> <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:skos="http://www.w3.org/2004/02/skos/core#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:foaf="http://xmlns.com/foaf/0.1/" xmlns:aos="http://aims.fao.org/aos/common/" > <skos:Concept rdf:about="http://aims.fao.org/aos/agrovoc/c_99"> <skos:prefLabel xml:lang="en">Acquired characters</skos:prefLabel> ……………………
| |
searchByModeLangScopeXML
simpleSearchByMode2
Name of Web Service | simpleSearchByMode2 (String searchString, String searchmode, String separator) | |
Description | This web service executes a simple search on all AGROVOC terms retrieving terms based on the specified search mode: Terms are retrieved having the search term either
In case, nothing is specified or the searchmode parameter is entered incorrectly, a partial search, i.e. containing the search term is executed by default. The search is not case sensitive, i.e. ‘Fruit’, ‘FRUIT’ and ‘fruit’ return the same results (for all search modes). No wild cards (like *) can be used. The difference to the searchByTerm web service is that this web service executes a simpler search, i.e. a search for ‘rice’ with the searchmode ‘containing’ also retrieves the AGROVOC term ‘Wholesale prices’ whereas the searchByTerm web service only retrieves AGROVOC terms that have the entire keyword ‘rice’ as one of the compounds, the term is made up of. | |
Parameters | String searchString | The search String |
String searchmode | The search mode: - starting - containing (default) - exact -end with -exact word | |
String separator | Any separator of your choice to separate the terms in the result string. The default separator is ||. | |
Return Values | String [(termcode,matchedTerms,languagecode)*, (NumberOfResults,numberOfResults)] | A string containing all the matched term’s termcodes, the terms themselves, followed by the respective 2 digit language code The last pair of values of any return string contains the total number of results |
Example | A search for ‘fruit’ and ‘starting’ and ‘--’ returns [3119--Fruit--EN--3119--Fruit--FR--9414--Fruit à pain--FR--11028--Fruit bats--EN--32457--Fruit cracking--EN--3120--Fruit crops--EN--3130--Fruit damaging insects--EN--16184--Fruit drop--EN--29024--Fruit extracts--EN--14827--Fruit flies--EN--25476--Fruit growing--EN--25764--Fruit harvesters--EN--28419--Fruit juice industry--EN--3123--Fruit juices--EN--32459--Fruit leathers--EN--3124--Fruit musts--EN--3125--Fruit products--EN--3126--Fruit pulps--EN--11030--Fruit purees--EN--16552--Fruit set--EN--11031--Fruit sugar--EN--3127--Fruit syrups--EN--35116--Fruit thinning--EN--34832--Fruit tree nurseries--EN--3128--Fruit trees--EN--3129--Fruit vegetables--EN--15971--Fruiting--EN--11032--Fruiting bodies (fungi)--EN--3131--Fruits--EN--3131--Fruits--FR--9238--Fruits à baie--FR--12873--Fruits à coque--FR--25461--Fruits à noyau--FR--25497--Fruits à pépins--FR--1248--Fruits confits--FR--25152--Fruits congelés--FR--32501--Fruits de contre-saison--FR--2005--Fruits de cucurbitacée--FR--35689--Fruits de mer--FR--29288--Fruits en conserve--FR--3099--Fruits frais--FR--2382--Fruits séchés--FR--14656--Fruits subtropicaux--FR--16491--Fruits surgelés--FR--7655--Fruits tempérés--FR--7974--Fruits tropicaux--FR--NumberOfResults--46] | |
getConceptInfoByTermcode
Name of Web Service | getConceptInfoByTermcode (String termCode) | |
Description | Returns the most important concept information of an AGROVOC term, i.e. its term code, labels in all languages and the term codes of its broader, narrower and related terms as well as of non-descriptor terms for which this concept is used. In case of a non-descriptor, it contains the link to its descriptor via the USE relationship. So compared to its previous version of this method (getConceptByTerm) it is now possible to navigate from and to non-descriptors. Also, now the termcode is used instead of the term, to avoid ambiguity (in case of two identical terms in different languages). | |
Parameters | String termcode | The termcode of the AGROVOC term for example 6599 for ‘rice’ |
Return Values | String [] concept | The Array of String containing the various parts of the concept. Each element of the array is inside []: [1] – labels of the term [2] – term codes of the terms (non-descriptors) this concept is used for (UF) [3] – term code(s) of the term’s descriptor(s) (USE) in case of a non-descriptor [4] – term codes of the concept’s broader terms (BT) [5] – term codes of the concept’s narrower terms (NT) [6] – term codes of the concept’s related terms (RT) |
Example | Submitting ‘6599’ returns the following : i.e. the termcode of rice (6599), followed by its labels in all available languages, followed by the termcodes of the concept’s non-descriptor (terms this concept is used for, in this case ‘Paddy’), the termcodes of the concept’s broader terms (here ‘Cereals’), its narrower terms and related terms (here: ‘Oryza’, ‘Rice straw’, ‘Rice flour’). Since it is a descriptor, there is no term linked to the USE relationship. | |
getConceptInfoByURI
Name of Web Service | getConceptInfoByURI(String ontologyName, String conceptURI, String format) | |
Description | The Method will return the concept information for the given URI. The result of this method will be in SKOS or TXT format. | |
Parameters | String ontologyName String conceptURI String format | |
Return Values | String result | It returns the results in SKOS or TXT format |
Example | ontologyName:Agrovoc conceptURI:http://aims.fao.org/aos/agrovoc/c_99 format:SKOS Output(sample): <skos:Concept rdf:about="http://aims.fao.org/aos/agrovoc/c_100"> <skos:prefLabel xml:lang="ar">أكري (برازيل)</skos:prefLabel> <skos:prefLabel xml:lang="cs">Acre (Brazílie)</skos:prefLabel> <skos:prefLabel xml:lang="de">ACRE</skos:prefLabel> <skos:prefLabel xml:lang="en">Acre (Brazil)</skos:prefLabel> <s
| |
getDefinitions
Name of Web Service | getDefinitions (String termcode, String languagecode ) | |
Description | Returns the history notes, definitions, scope notes. | |
Parameters | String termcode
| The AGROVOC internal term code (retrieved for example by invoking the getTermCodeByTerm web service) |
String languagecode | The two letter language code taken from the above list | |
Return Values | String [] definitions | An Array of String containing the various existing notes and definitions. Each element of the array is a String inside [] [0] – the term’s scope notes [1] – the term’s history notes [2] – the term’s definitions [3] – the term’s other comments |
Example | The termcode 2345 (‘Division of labour’) in language English (en) returns the following: [[Scope Note:, Physical division of labour; for the international division of labour use <3915> and <6205>], [History Note:], [Definition:], [Comment:]] | |
getAllLabelsByTermcode2
Name of Web Service | getAllLabelsByTermcode2(String termcode, String separator) | |
Description | Returns labels in all available languages of an AGROVOC term specified by its termcode. | |
Parameters | String termcode | The internal AGROVOC termcode |
String separator | Any separator of your choice to separate the terms in the result string. The default separator is ||. | |
Return Values | String termLabels | A String containing all the labels, each label followed by its languages, i.e. [term1,languagecode,term2,languagecode,...] |
Example | Calling the web service with 5644 and || returns [لآلئ||AR||perly||CS||PERLE||DE||Pearls||EN||Perlas||ES||مرواریدها|| FA||Perle||FR||मोती||HI||gyöngy||HU||Perle||IT|| 真珠||JA||ຫອຍໃຫ້ໄຂ່ມຸກ||LO||Perła||PL||Pérola||PT||perly||SK||หอยมุก||TH|| 珍珠||ZH] i.e. 5644 has the label Pearls in English, Perlas in Spanish, etc. The unreadable characters are due to the encoding. | |
getTermByLanguage
Name of Web Service | getTermByLanguage (String termcode, String language | |||
Description | Returns the label of a term specified by its AGROVOC internal termcode and the language code. Can specify more than one language code using comma separator
| |||
en – English fr – French es – Spanish | ar – Arabic zh – Chinese | pt – Portuguese cs – Czech
| ||
Parameters | String termcode
| The AGROVOC internal term code (retrieved for example by invoking the getTermCodeByTerm web service) | ||
String language | The two letter language code taken from the above list | |||
Return Values | String term | The label of the correspondent AGROVOC term in the specified language | ||
Example | Invoking getTermByLanguage (3456,‘en’) returns “Habitats” | |||
getURIByTermAndLangXML
|
| |
Name of Web Service | getURIByTermAndLangXML(String ontologyName, String term, String searchMode, String format, String lang) | |
Description | The Method will return the list of concept URI for the given term, search filter and language. The result of this method will be in TXT or SKOS format. | |
Parameters | String ontologyName String term String searchMode (contains, exact match, starts with, ends with, exact word) String format String lang
| |
Return Values | String result | It returns an URI for the given term. |
Example | ontologyName:Agrovoc term:Acquired characters searchMode:Exact Match format:SKOS lang:All Output: <?xml version="1.0" encoding="utf-8"?> <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:skos="http://www.w3.org/2004/02/skos/core#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:foaf="http://xmlns.com/foaf/0.1/" > <skos:Concept rdf:about="http://aims.fao.org/aos/agrovoc/c_99"> </skos:Concept> </rdf:RDF>
| |
getFullAuthority
Name of Web Service | getFullAuthority(string authorityFile, string searchString, string searchCriteria, string lang, string format) | |
Description | The web service will provide the search for all Authority files in any language. The search can have different search criteria. The result of the search should list all pertinent Authority files visualizing the LABEL in different languages and all the relevant attributes. For projects the search is carried out in the label and project code fields. The cataloguer will choose one or more values and get the URI together with the Authority file. All the information related to the Authority file should be retrieved just invoking the getFullAuthority method. It calls getConceptByKeyword | |
Parameters | String ontologyName String searchString String searchMode (contains, exact match, starts with, ends with, exact word) String lang String format | |
Return Values | String result
| It returns the full authority control file data. |
Example | ontologyName: projects searchString:Action searchMode:Starts With lang: All format: SKOS | |
getConceptByURI
Name of Web Service | getConceptByURI(string authorityFile, string conceptURI, string format) | |
Description | The Method will return concepts with given keyword, and can filter with the language. The result of this method will be in TXT or SKOS format.. | |
Parameters | String ontologyName String conceptURI String format | |
Return Values | String result | It returns the concepts from a given keyword |
Example | ontologyName: corporate_bodies conceptURI: http://aims.fao.org/aos/corporate/c_3870 format: SKOS | |
getConceptByRelationshipValue
Name of Web Service | getConceptByRelationshipValue(string authorityFile, string relationURI, string value, string searchMode, string lang, string format) | |
Description | The Method getConceptByRelationshipValue will return the list of URI in the given OntologyName , RelationURI, value and lang. The result of this method will be in TXT format. | |
Parameters | String ontologyName String relationURI String value String searchMode String lang String format | |
Return Values | String result | It returns the list of URIs. |
Example | relationURI: http://aims.fao.org/aos/common/hasNumber value: AFG/018/NET searchMode:Starts With lang: en format: TXT | |
getlatestUpdates
Name of Web Service | getLatestUpdates(string authorityFile, string dateFrom, string dateTo, string format) | |
Description | The web service will allow extracting all records that have changed for given period of time. It will be used to run the Reconciliation procedure. | |
Parameters | String ontologyName String dateFrom String dateTo String format | |
Return Values | String result | It returns the latest update of data in the SKOS format |
Example | ontologyName: projects dateFrom: 01/01/2009 dateTo: 01/01/2010 format: SKOS | |
getTermcodeByTermAndLangXML
Name of Web Service | getTermCodeByTermAndLangXML(String ontologyName, String term, String lang, String codeName, String format) | |
Description | The Method will return the list of terms code in the given term and language. The result of this method will be in TXT or SKOS format. | |
Parameters | String ontologyName String term String lang String codeName String format | |
Return Values | String result | It returns a list of terms codes |
Example | ontologyName: Agrovoc term:Acquired characters lang:en codeName: hasCodeAgrovoc format: SKOS
<?xml version="1.0" encoding="utf-8"?> <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:skos="http://www.w3.org/2004/02/skos/core#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:foaf="http://xmlns.com/foaf/0.1/" > <skos:Concept rdf:about="http://aims.fao.org/aos/agrovoc/c_99"> <skos:note xml:lang="en">Has AGROVOC term code:99</skos:note> </skos:Concept> </rdf:RDF> | |
getTermExpansion
getReleaseDate
Name of Web Service | getReleaseDate() | |
Description | The Method will return the release date of the dataset | |
Parameters | ||
Return Values | String result | It returns the release date of the dataset |
Example |
no release date | |
getWebServicesVersion
Name of Web Service | getWebServicesVersion() | |
Description | The Method will return the version of the deployed web services | |
Parameters | ||
Return Values | String result | It returns the version of the deployed web services |
Example |
0.2.0 | |
SPARQL queries using OWLIM (Lucene) indexes.
In OWLIM, is it posibile to search in the Literals using LUCENE's indexes.
First of all, you should create these indexes. To do so, you need to execute the two following update queries:
PREFIX luc: <http://www.ontotext.com/owlim/lucene#>
INSERT DATA {
luc:moleculeSize luc:setParam "1" .
luc:languages luc:setParam "" .
luc:include luc:setParam "centre" .
luc:index luc:setParam "literals" .
}
PREFIX luc: <http://www.ontotext.com/owlim/lucene#>
INSERT DATA {
<http://www.ontotext.com/owlim/lucene#agrovoc> luc:createIndex "true" .
}
Where <http://www.ontotext.com/owlim/lucene#agrovoc> is the name of the indexes, you can use a different URI to idendify the indexes, but you should rememeber to use it in the other SPARQL queries as well.
Then to retrieve the literals using the new indexes you can do:
SELECT ?label
WHERE{
?label <http://www.ontotext.com/owlim/lucene#agrovoc> "dog*" .
FILTER( langMatches(lang(?label), "en")) .
}
To retrieve all the literals which start with the word dog and are in English.
You can find more information on how to use these indexes to execute a full text search from the official page of OWLIM: http://owlim.ontotext.com/display/OWLIMv53/OWLIM-SE+Full-text+Search
Some of the Web Services are using these indexes if the config parameter "owlim.useIndexes" is set to true (the first time you need to set to true also the config paramter "owlim.reloadIndexes" to create these indexes)
