Search Concept Web Service

The Search Web service is used to find UMBEL reference
concepts that match a search string. This is the primary tool for
finding available concepts in the reference structure.

Usage

This Web service is intended to be used by any user that wants to find
UMBEL reference concepts using a full text search engine.
No permissions are required to query this web service endpoint. To
access this endpoint, you simply have to send a HTTP GET
query to the proper endpoint URL per the specifications below.

HTTP Method:

GET

Possible Accept: HTTP header field value:

application/json: return the JSON serialization of the resultset

application/*: return the JSON serialization of the resultset

*/*: return the JSON serialization of the resultset

URL:

http://umbel.org/ws/search/query/page

http://umbel.org/ws/search/query/autocomplete

Parameters:

query: this is the url-encoded full
text search string to send to the endpoint.
The
Lucene Query Parser Syntax is supported.
Additionally, you can prefix all your queries the following
prefixes to restrict your search on one of these
field:

pref-label: perform a search query for the preferred labels of the concepts only

alt-labels: perform a search query for the alternative labels of the concepts only

description: perform a search query for the description of the concepts only

type: perform a search query for the type of the concepts only

uri: perform a search query for the URI of the concepts only

page: this is the page of the results you want to
get from the endpoint. The endpoint returns
10 results for every query. The page index starts
at 0. This means that if you want to get the
results 10 to 20 then the page parameter needs to be 1

autocomplete: this parameter specify that you want to perform
an autocompletion search against the UMBEL
reference concept structure. This is optimized for
searching from the start of the preferred labels
of the concepts and to return the top 10 results
that match the search query. Note that this parameter
cannot be used with the page
parameter.

Serializations

Normal Search Query

The search endpoint currently supports a single serialization format:
JSON.

The JSON structure of a search resultset is an object composed of:

"nb-results" — an attribute that specify
the number of results that match the
query

"results" — an attribute that refer to an
array of results records

Then, each result record object is composed of:

"type": specify an array of type URIs for the concept

"description": specify a string that describes the concept

"pref-label: specify a string that represent the preferred label to use to refer to the concept

"alt-labels": specify an array of alternative labels to use to refer to the concept

"uri": specify a string that represent the URI of the concept

A search JSON resultset with a single result looks like:

{
"nb-results": 83,
"results": [
{
"type": [
"http://www.w3.org/2002/07/owl#Class",
"http://umbel.org/umbel#RefConcept",
"http://umbel.org/umbel/rc/Agents_Topic",
"http://www.w3.org/2002/07/owl#NamedIndividual"
],
"description": "A specialization of SocialBeing and IndividualAgent: the collection of all persons. Personhood is a vague, emotionally loaded yet extremely salient concept with respect to common-sense reasoning. Something is an instance of Person if it is an individual IntelligentAgent with perceptual sensibility, capable of complex social relationships, and possessing a certain moral sophistication and an intrinsic moral value, or -- if it lacks certain of these characteristics -- is a member of a distinct type of SocialBeing (usually a species) which generally possesses such characteristics and is therefore acknowledged by other members of that type as a person within their social systems. Most currently known instances of Person are instances of HomoSapiens but there is no reason why all need be (consider Hobbits in the fictional world of LordOfTheRings_Trilogy). They need not even be instances of BiologicalLivingObject (consider the possibility of a person-like AI). Also note that Person excludes non-human \"legal persons\", who are, however, included in the collection LegalAgent.",
"alt-labels": [
"human",
"mortals",
"manpower",
"mortal",
"people",
"persons",
"laymen",
"layman"
],
"pref-label": "person",
"uri": "http://umbel.org/umbel/rc/Person"
}
]
}

Autocompletion Search Query

The JSON structure of an autocompletion search resultset is an array of objects:

"label" — The preferred label of the reference concept that match the
query.

Performing an autocompletion search that match any word that starts with "Per"

Errors

Here is the list of possible HTTP errors that can be returned by this endpoint:

HTTP Error

Message

Description

404

empty

The URL of the web service is not properly constructed. This usually happens if
you write URLs like http://umbel.org/ws/search/person/ (see the ending slash)
or http://umbel.org/ws/search/person/pagee/1 (see the type with the
"page" parameter)

406

Unsuppoted mime requested

The Accept: HTTP headers doesn't contain any supported mime types.
If this happens, make sure that you are requesting a supported mime type.

500

empty

An internal UMBEL Web service error occurred. If this happens, please contact us
with the query that caused the error.