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 support 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 are 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.
  • "uri" — The URI of the reference concept that match the query
An autocompletion search JSON resultset looks like:
 
  [
      {
          "label": "person",
          "uri": "http://umbel.org/umbel/rc/Person"
      },
      {
          "label": "person in a relationship",
          "uri": "http://umbel.org/umbel/rc/InvolvedInRelationship"
      },
      {
          "label": "person of mixed race",
          "uri": "http://umbel.org/umbel/rc/EthnicGroupOfMixedRace"
      },
      {
          "label": "person types",
          "uri": "http://umbel.org/umbel#PersonTypes"
      },
      {
          "label": "person who delivers milk to households",
          "uri": "http://umbel.org/umbel/rc/DairyBeverageDeliveryProfessional"
      }
  ]
          

Examples

Here are a series of examples that uses cURL for querying the search web service endpoint.
 
Performing a search for the keyword "Person"
  curl -H "Accept: application/json" "http://umbel.org/ws/search/person"
 
Performing a search for the keyword "Person" but return results 10 to 20
  curl -H "Accept: application/json" "http://umbel.org/ws/search/person/page/1"
 
Performing a search for the keyword "Person" but only query the preferred label of the concepts
  curl -H "Accept: application/json" "http://umbel.org/ws/search/pref-label:person"
 
Performing a search for the keyword "Person" or "Agent"
  curl -H "Accept: application/json" "http://umbel.org/ws/search/person OR agent"
 
Performing a search that match any word that starts with "Per"
  curl -H "Accept: application/json" "http://umbel.org/ws/search/per*"
 
Performing an autocompletion search that match any word that starts with "Per"
  curl -H "Accept: application/json" "http://umbel.org/ws/search/per/autocomplete"
 

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.
 

Copyright © 2008-2014. Structured Dynamics LLC. All content available via Creative Commons Attribution 3.0