XSearch-Service-API

From Gcube Wiki
Jump to: navigation, search

Objective

  • The objective of this activity is to provide an API for the semantic post-processing services of search results that were developed in the context of T10.4.

Requirements

  • The API should allow someone to build an application (web application, mobile application) that exploits the services of T10.4 (and their deployment in the infrastructure).
  • The functionality of 10.4 is generic, i.e. one can configure the underlying search system, the desired categories, the SPARQL endpoints to be used. It is desirable to offer this generality also at the API level.

Decisions

  • We plan to develop a REST API since such an API could be used easily in various contexts.
  • We will comply with OpenSearch because it is a standard and can allow configuring the underlying search system to use.

Services

Main Service A: Post-processing of search results

This service is responsible for the post-proccessing of the search results by performing textual clustering, entity mining or both in the top search results as returned by the given search system. The API accepts (as input parameters) an underlying search system and a set of parameters (e.g. query, number of results to analyze, etc.). The underlying source can be an opensearch compliant search engine. XSearch is then responsible for sending the query (with the given parameters) to the search engine and retrieve the results. Additional parameters related to the tasks of entity mining and textual clustering will be provided to the API.

Input Parameters:

  • searchsystem: The name of a supported search system - Required. Valid values: see Supported Service S3.
  • query: The query string - Required in case searchsystem != gcube
  • descrdoc: The URL of an OpenSearch Description Document - Required in case searchsystem=opensearch
  • locator: The gCube ResultSet locator - Required in case searchsystem=gcube
  • numofresults: Number of results to analyze (integer). Default: 100
  • mining: Enable or not Entity Mining. Valid values: {true, false}. Default: true
  • categories: Active categories of entities (semicolon-separated names of categories) (see Supported Service S1). Default: X-Search's current active categories.
  • clustering: Enable or not Textual Clustering. Valid values: {true, false}. Default: true
  • numofclusters: Number of clusters to return (integer). Default: 15
  • clusteringalg: ID of clustering algorithm. Valid values: see Supported Service S2. Default: cl3
  • typeofresults: Type of results to analyze. Valid values: {snippets, contents}. Default: snippets
  • format: The output format. Valid values: {json, xml}. Default: json (CSV is not supported since we cannot describe the complex results of this service through CSV)

Output:

  • The input parameters
  • Detected Entities (and for each entity, the results in which it lies)
  • Produced Clusters (and for each cluster, the results in which it lies)
  • Results
  • Date of request

Example:

REST call:

http://.../xsearch-service-2.0.0/api/processresults?searchsystem=opensearch&query=tuna&numofresults=50&format=json&descrdoc=http://users.ics.forth.gr/~fafalios/bing.xml

JSON result:

{
   "result": {
       "inputParameters": {
           "mining": true,
           "locator": "",
           "searchsystem": "opensearch",
           "query": "tuna",
           "typeofresults": "snippets",
           "numofresults": 50,
           "descrdoc": "http://users.ics.forth.gr/~fafalios/bing.xml",
           "categories": ["Regional_Fisheries_Body", "Country", "Species", "Water_Area"],
           "format": "json",
           "clusteringalg": "cl3",
           "numofclusters": 15,
           "clustering": false
       },
       "resultOfEntityMining": [
           {
               "categoryName": "Species",
               "rank": 1,
               "entities": [
                   {
                       "score": 116,
                       "documentsIDs": [0,9,22],
                       "entityName": "Scombridae"
                   },
                   {
                       "score": 89,
                       "documentsIDs": [0,9],
                       "entityName": "Thunnini"
                   },
                   {
                       "score": 47,
                       "documentsIDs": [2],
                       "entityName": "salmon"
                   },
                   {
                       "score": 111,
                       "documentsIDs": [2,12,29,44,47],
                       "entityName": "albacore"
                   },
                   {
                       "score": 115,
                       "documentsIDs": [6,18,28,29],
                       "entityName": "Thunnus"
                   },
                   {
                       "score": 5,
                       "documentsIDs": [44],
                       "entityName": "Bonito"
                   }
               ]
           },
           {
               "categoryName": "Country",
               "rank": 2,
               "entities": [
                   {
                       "score": 39,
                       "documentsIDs": [10],
                       "entityName": "United States"
                   },
                   {
                       "score": 38,
                       "documentsIDs": [11],
                       "entityName": "Japan"
                   },
                   {
                       "score": 29,
                       "documentsIDs": [20],
                       "entityName": "Mexico"
                   }
               ]
           },
           {
               "categoryName": "Water_Area",
               "rank": 3,
               "entities": [
                   {
                       "score": 42,
                       "documentsIDs": [7],
                       "entityName": "Atlantic"
                   },
                   {
                       "score": 14,
                       "documentsIDs": [35],
                       "entityName": "Mediterranean"
                   }
               ]
           }
       ],
       "resultOfClustering": [
           {
               "rank": 1,
               "clusterLabel": "food",
               "documentsIDs": [43,41,39,35,29,18,6,1]
           },
           {
               "rank": 2,
               "clusterLabel": "recipes",
               "documentsIDs": [47,34,12,8,2,1]
           },
           {
               "rank": 3,
               "clusterLabel": "canned",
               "documentsIDs": [47,33,24,21,10,2]
           },
           {
               "rank": 5,
               "clusterLabel": "good",
               "documentsIDs": [46,40,39,33]
           },
           {
               "rank": 6,
               "clusterLabel": "free",
               "documentsIDs": [18,15,0]
           },
           {
               "rank": 7,
               "clusterLabel": "encyclopedia",
               "documentsIDs": [28,15,0]
           },
           {
               "rank": 8,
               "clusterLabel": "definition",
               "documentsIDs": [29,18,6]
           },
           {
               "rank": 9,
               "clusterLabel": "bluefin",
               "documentsIDs": [49,32,11,7]
           },
           {
               "rank": 10,
               "clusterLabel": "healthy",
               "documentsIDs": [47,21,2]
           },
           {
               "rank": 11,
               "clusterLabel": "safe",
               "documentsIDs": [46,24,16
               ]
           }
       ],
       "topResults": [
           {
               "id": 0,
               "rank": 1,
               "title": "Tuna - Wikipedia, the free encyclopedia",
               "description": "A tuna is a saltwater finfish that belongs to the tribe Thunnini, a sub-grouping of the mackerel family (Scombridae) – which together with the tunas, also includes ...",
               "url": "http://en.wikipedia.org/wiki/Tuna"
           },
           {
               "id": 1,
               "rank": 2,
               "title": "Tuna Recipes : Food Network",
               "description": "Find tuna recipes, videos, and ideas from Food Network.",
               "url": "http://www.foodnetwork.com/topics/tuna.html"
           },
           {
               "id": 2,
               "rank": 3,
               "title": "Bumble Bee Foods - Tuna Fish | Healthy Seafood Recipes ...",
               "description": "International company selling canned tuna, albacore, salmon, crab meat, shrimp, oysters, and clams. Company profile, product information, tunafish information ...",
               "url": "http://www.bumblebee.com/"
           },
           {
               "id": 3,
               "rank": 4,
               "title": "Tuna ft. Cozman - Fenix (Official Video HD) - YouTube",
               "description": "Executive Producer: Altuna Sejdi, Publisher: Acromax GmbH Music: Getoar Selimi, Lyrics: Getoar Selimi Music produced by: Zzap & Chriss, Video produced by ...",
               "url": "http://www.youtube.com/watch?v=3KhYDv7Se6A"
           },
           {
               "id": 4,
               "rank": 5,
               "title": "Tuna - I Asaj (Official Video) - YouTube",
               "description": "Faqja Zyrtare ne Fb : https://www.facebook.com/officialTUNA Executive Producer & Rightsholder: Altuna Sejdi Video by: Entermedia Music by: BIGBANGBEATS ...",
               "url": "http://www.youtube.com/watch?v=D3xCOodYsvs"
           },
           {
               "id": 5,
               "rank": 6,
               "title": "Tuna - The World's Healthiest Foods",
               "description": "An Important Message About Tuna. We have placed tuna on our \"10 Most Controversial WHFoods List.\" This list was created to let you know that even though some foods ...",
               "url": "http://www.whfoods.com/genpage.php?tname=foodspice&dbid=112"
           },
           {
               "id": 6,
               "rank": 7,
               "title": "tuna: Definition from Answers.com",
               "description": "tuna n. , pl. , tuna , or -nas . Any of various often large scombroid marine food and game fishes of the genus Thunnus and related genera, many of which,",
               "url": "http://www.answers.com/topic/tuna-salad"
           },
           {
               "id": 7,
               "rank": 8,
               "title": "Tuna | Species | WWF - World Wildlife Fund",
               "description": "Tuna are among the most commercially valuable fish on the planet. The Atlantic bluefin is a highly sought-after delicacy for sushi and sashimi in Asia—a single fish ...",
               "url": "http://worldwildlife.org/species/tuna"
           },
           {
               "id": 8,
               "rank": 9,
               "title": "Tuna Recipes - Allrecipes.com",
               "description": "Tuna steaks and cakes. Tuna casseroles and melts. Tuna salads and more. We have hundreds of 5-star recipes for tuna, the incredibly versatile fish.",
               "url": "http://allrecipes.com/Recipes/Seafood/Fish/Tuna/"
           },
           {
               "id": 9,
               "rank": 10,
               "title": "Tuna - Rhode Island Sea Grant",
               "description": "TUNA P1412 By Elizabeth Gibbs. Tuna are finfish belonging to the tribe Thunnini, a sub-grouping of the mackerel family (Scombridae), which also includes ...",
               "url": "http://seagrant.gso.uri.edu/factsheets/tuna.html"
           },
           {
               "id": 10,
               "rank": 11,
               "title": "StarKist Tuna",
               "description": "United States based canned and shelf stable pouch tuna packer. Product information, recipes, and contact details.",
               "url": "http://starkist.com/"
           },
           {
               "id": 11,
               "rank": 12,
               "title": "Bluefin Tuna Goes For Record $736,000 At Tokyo's Tsukiji ...",
               "description": "TOKYO -- This tuna is worth savoring: It cost nearly three-quarters of a million dollars. The bluefin tuna caught off northeastern Japan fetched a record ...",
               "url": "http://www.huffingtonpost.com/2012/01/05/bluefin-tuna-record_n_1185770.html"
           },
           {
               "id": 12,
               "rank": 13,
               "title": "Fresh Tuna Recipes - Martha Stewart",
               "description": "Albacore, bigeye, yellowfin, bluefin, skipjack: These are all types of tuna, game fish whose firm flesh are ideal for cutting into steaks. High-quality fresh tuna is ...",
               "url": "http://www.marthastewart.com/343354/fresh-tuna-recipes"
           },
           {
               "id": 13,
               "rank": 14,
               "title": "Tuna | Seafood Selector",
               "description": "Some kinds of tuna are high in mercury, a serious health risk for kids and pregnant women. Our seafood selector can help you make safer choices.",
               "url": "http://seafood.edf.org/tuna"
           },
           {
               "id": 14,
               "rank": 15,
               "title": "Bodybuilding.com - 8 Ways To Prepare Tuna: Never Be Bored ...",
               "description": "Italian Tuna Pita. A great option for a fast lunch, this Italian tuna pita is easy to store as a quick snack for when you're trying to increase your calorie intake.",
               "url": "http://www.bodybuilding.com/fun/8-ways-to-prepare-tuna.html"
           },
           {
               "id": 15,
               "rank": 16,
               "title": "Opuntia - Wikipedia, the free encyclopedia",
               "description": "The fruit of prickly pears, commonly called cactus fruit, cactus fig, Indian fig or tuna in Spanish, is edible, although it has to be peeled carefully to remove the ...",
               "url": "http://en.wikipedia.org/wiki/Opuntia"
           },
           {
               "id": 16,
               "rank": 17,
               "title": "Tuna Calculator | Environmental Working Group",
               "description": "How much tuna can you eat safely? EWG tells you what the FDA won't. This site uses the FDA's own scientific guidelines for what constitutes a safe dose of mercury to ...",
               "url": "http://www.ewg.org/research/tuna-calculator"
           },
           {
               "id": 17,
               "rank": 18,
               "title": "TUNA",
               "description": "",
               "url": "http://tuna.gr.jp/"
           },
           {
               "id": 18,
               "rank": 19,
               "title": "tuna - definition of tuna by the Free Online Dictionary ...",
               "description": "tu·na 1 (to̅o̅′nə, tyo̅o̅′-) n. pl. tuna or tu·nas. 1. a. Any of various often large scombroid marine food and game fishes of the genus Thunnus and related ...",
               "url": "http://www.thefreedictionary.com/tuna"
           },
           {
               "id": 19,
               "rank": 20,
               "title": "@ tuna",
               "description": "Species and marketing information for the tuna fishing industry.",
               "url": "http://www.atuna.com/"
           },
           {
               "id": 20,
               "rank": 21,
               "title": "Tuna | Define Tuna at Dictionary.com",
               "description": "noun . 1. any of various prickly pears, especially either of two erect, treelike species, Opuntia tuna or O. ficus-indica, of Mexico, bearing a sweet, edible fruit.",
               "url": "http://dictionary.reference.com/browse/tuna"
           },
           {
               "id": 21,
               "rank": 22,
               "title": "Canned Tuna Fish, Chunk Light Tuna, Tuna Fillet | Bumble ...",
               "description": "Check out Bumble Bee's assortment of high quality tuna fish cans in oil and water, along with quick and healthy tuna recipes.",
               "url": "http://www.bumblebee.com/products/tuna/"
           },
           {
               "id": 22,
               "rank": 23,
               "title": "Tuna - Wikipedija",
               "description": "Tuna (tunj) rod riba porodice Scombridae ili skušovki, red grgečki . Narastu dužine preko četiri metra, vrsni su plivači i grabežljivci koji se hrane drugom ribom .",
               "url": "http://hr.wikipedia.org/wiki/Tuna"
           },
           {
               "id": 23,
               "rank": 24,
               "title": "Tuna | Greenpeace International",
               "description": "Globally tuna populations are in trouble. Every year there are more boats chasing fewer tuna as populations all around the world are declining.",
               "url": "http://www.greenpeace.org/international/en/campaigns/oceans/tuna/"
           },
           {
               "id": 24,
               "rank": 25,
               "title": "Mercury alert: Is canned tuna safe to eat? | Environmental ...",
               "description": "Tuna can contain mercury, so parents must choose wisely when serving it to their kids, and be aware that school lunches may have unsafe levels.",
               "url": "http://www.edf.org/oceans/mercury-alert-canned-tuna-safe-eat"
           },
           {
               "id": 25,
               "rank": 26,
               "title": "Tuna - Wikipedia, la enciclopedia libre",
               "description": "Una Tuna es una hermandad de estudiantes universitarios que portan una combinación de vestimentas antiguas y que interpretan temas musicales del folclore europeo e ...",
               "url": "http://es.wikipedia.org/wiki/Tuna"
           },
           {
               "id": 26,
               "rank": 27,
               "title": "Tuna",
               "description": "In most years the tuna that are seen and caught near Provincetown at the tip of Cape Cod, and in Cape Cod Bay, are small (so-called \"school fish\") weighing ...",
               "url": "http://www.gma.org/fogm/Thunnus_thynnus.htm"
           },
           {
               "id": 27,
               "rank": 28,
               "title": "tuna.be",
               "description": "We would like to show you a description here but the site won’t allow us.",
               "url": "http://tuna.be/pc/"
           },
           {
               "id": 28,
               "rank": 29,
               "title": "tuna (fish) -- Encyclopedia Britannica",
               "description": "tuna (genus Thunnus), also called tunny , any of seven species of oceanic fishes, some very large, that constitute the genus Thunnus and are of great commercial value ...",
               "url": "http://www.britannica.com/EBchecked/topic/608882/tuna"
           },
           {
               "id": 29,
               "rank": 30,
               "title": "tuna - Definition of tuna - YourDictionary",
               "description": "noun pl. tuna or tunas. any of various, usually large, marine, scombroid, food and game fishes (esp. genus Thunnus), including the albacore; the flesh of various ...",
               "url": "http://www.yourdictionary.com/tuna"
           },
           {
               "id": 30,
               "rank": 31,
               "title": "Hollywood Tuna",
               "description": "Daily Tuna. March 11th, 2014 Tweet-Aubrey O’Day is great at Instagram-Sexy girls in sports bras!-Paris Hilton should’ve worn a bikini-Lindsay Lohan is a mess",
               "url": "http://www.hollywoodtuna.com/"
           },
           {
               "id": 31,
               "rank": 32,
               "title": "Hot Tuna -",
               "description": "The year-end Hot Tuna shows at the Fur Peace Ranch have been sold out for months, but that doesn’t mean you have to wait for 2014 to see them again.",
               "url": "http://hottuna.com/"
           },
           {
               "id": 32,
               "rank": 33,
               "title": "Bluefin Tuna, Bluefin Tuna Pictures, Bluefin Tuna Facts ...",
               "description": "Learn all you wanted to know about bluefin tuna with pictures, videos, photos, facts, and news from National Geographic.",
               "url": "http://animals.nationalgeographic.com/animals/fish/bluefin-tuna/"
           },
           {
               "id": 33,
               "rank": 34,
               "title": "Is Canned Tuna Good for You? | LIVESTRONG.COM",
               "description": "Mercury. Although canned tuna has several health benefits, it does contain mercury, a metal that can have adverse effects on the nervous system and brain ...",
               "url": "http://www.livestrong.com/article/376793-is-canned-tuna-good-for-you/"
           },
           {
               "id": 34,
               "rank": 35,
               "title": "Tuna Cakes Recipe - Kraft Recipes - Great Recipes, Dinner ...",
               "description": "Forget everything you know about tuna cakes. Simple, cheesy and held together with hearty stuffing, these'll win over even those determined not to like seafood.",
               "url": "http://www.kraftrecipes.com/recipes/tuna-cakes-109716.aspx"
           },
           {
               "id": 35,
               "rank": 36,
               "title": "Mediterranean Tuna Wrap Recipe : Ellie Krieger : Food Network",
               "description": "Get this all-star, easy-to-follow Mediterranean Tuna Wrap recipe from Ellie Krieger.",
               "url": "http://www.foodnetwork.com/recipes/ellie-krieger/mediterranean-tuna-wrap-recipe.html"
           },
           {
               "id": 36,
               "rank": 37,
               "title": "Tuna Bora",
               "description": "Comic Con Sketchbook. gouache. Kite",
               "url": "http://www.tunabora.com/"
           },
           {
               "id": 37,
               "rank": 38,
               "title": "What Is a Tuna? (with pictures) - wiseGEEK",
               "description": "There are nine recognized species of tuna, which is a marine fish which spends the majority of its life in the middle depths of open water. Tuna is probably the most ...",
               "url": "http://www.wisegeek.org/what-is-a-tuna.htm"
           },
           {
               "id": 38,
               "rank": 39,
               "title": "Tuna - Kitchen Dictionary - Food.com",
               "description": "Learn about tuna in the Kitchen Dictionary - Food.com: Talk with your mouth full",
               "url": "http://www.food.com/library/tuna-395"
           },
           {
               "id": 39,
               "rank": 40,
               "title": "Tuna | BBC Good Food",
               "description": "A member of the mackerel family, tuna are mainly found in the world's warmer oceans. They can grow to a huge size (up to 700kg) and their meaty flesh is distinctively ...",
               "url": "http://www.bbcgoodfood.com/glossary/tuna"
           },
           {
               "id": 40,
               "rank": 41,
               "title": "Grilling Tuna",
               "description": "Tuna is one of the most popular and versatile fish on the market. If you buy good quality tuna you don't even need to cook it. Of course grilling adds flavor and ...",
               "url": "http://bbq.about.com/od/fishandseafood/a/aa103004a.htm"
           },
           {
               "id": 41,
               "rank": 42,
               "title": "Tuna: The new health food - SHEKNOWS",
               "description": "Tuna is a natural source of special omega-3s. You've undoubtedly heard of the virtues of omega-3 fatty acids — the media has extolled their health benefits and food ...",
               "url": "http://www.sheknows.com/health-and-wellness/articles/807195/tuna-the-new-health-food"
           },
           {
               "id": 42,
               "rank": 43,
               "title": "Barbie's Tuna Salad Recipe - Allrecipes.com",
               "description": "Curry and Parmesan cheese are the secret ingredients in this tuna salad recipe! I have never tasted another tuna salad like it.",
               "url": "http://allrecipes.com/Recipe/Barbies-Tuna-Salad/"
           },
           {
               "id": 43,
               "rank": 44,
               "title": "Tuna - The RuneScape Wiki",
               "description": "Tuna is a food item made by cooking raw tuna. Compared to many other fish, it is not the most potent healing item, but its low cost and high availability make it a ...",
               "url": "http://runescape.wikia.com/wiki/Tuna"
           },
           {
               "id": 44,
               "rank": 45,
               "title": "Tuna - ChefShop",
               "description": "Ortiz Bonito Del Norte Tuna Tin As seen in Wall Street Journal $7.99 Ortiz Ventresca Tuna In Olive Oil $17.99 Papa George Albacore Tuna $7.99",
               "url": "http://chefshop.com/Tuna-C336.aspx"
           },
           {
               "id": 45,
               "rank": 46,
               "title": "Tuna - Navy",
               "description": "Tuna . Any of numerous large, vigorous, spiny-finned fishes including some highly esteemed for sport and food. _____ Submarine No. 27 was laid down as Tuna on 20 ...",
               "url": "http://www.history.navy.mil/danfs/t9/tuna-ii.htm"
           },
           {
               "id": 46,
               "rank": 47,
               "title": "Is Tuna Good or Bad - How Much Tuna is Safe to Eat ...",
               "description": "Tuna is a high quality protein with almost no fat. It contains all essential amino acids required by the body for growth and maintenance of lean muscle tissue.",
               "url": "http://kosherfood.about.com/od/tunafish/qt/tuna.htm"
           },
           {
               "id": 47,
               "rank": 48,
               "title": "Healthy Tuna Recipes | Eating Well",
               "description": "Whether grilled, baked or flaked, these healthy tuna recipes from EatingWell use canned albacore tuna and fresh tuna in delicious meals for lunch or dinner.",
               "url": "http://www.eatingwell.com/recipes_menus/collections/healthy_tuna_recipes"
           },
           {
               "id": 48,
               "rank": 49,
               "title": "Tuna Fishing - Newport Landing",
               "description": "Tuna fishing details from varieties of tuna caught to techniques for catching tuna in Los Angeles and Southern California",
               "url": "http://www.newportlanding.com/tunafishing.html"
           },
           {
               "id": 49,
               "rank": 50,
               "title": "Wicked Tuna | National Geographic Channel",
               "description": "Wicked Tuna Rail Related Content The Bluefin Tuna Can It Be Fished Sustainably? June 11, 2012. The endangered bluefin is at the complex intersection of science ...",
               "url": "http://channel.nationalgeographic.com/channel/wicked-tuna/"
           }
       ],
       "date": "12/03/2014 11:38:43"
   }
}

Main Service B: Match an identified entity

This service links the name of an entity with a resource in a Knowledge Base. For example, the service can match the name "yellowfin tuna" with the DBpedia resource "http://dbpedia.org/resource/Yellowfin_tuna".

Input Parameters:

  • name - The name of the entity (string) - required
  • category - The category of the entity (string) - required
  • endpoint - The SPARQL endpoint to use (url). Default: the endpoint that has been configured in X-Search for the given category name.
  • tquery - The SPARQL template query to use (string). Default: the template query that has been configured in X-Search for the given category name.
  • format: The output format. Valid values: {json, xml, csv}. Default: json

Output:

  • The semantic information that is returned by running the SPARQL template query for the given name and category at the SPARQL endpoint.

Examples:

Consider that for the category "Species", the specified SPARQL endpoint is: http://virtuoso.i-marine.d4science.org:8890/sparql and the specified template query is:

define input:inference <http://www.ics.forth.gr/isl/Schema>
select distinct ?URI ?Value  
FROM <http://www.ics.forth.gr/isl/SameAs>
FROM <http://www.ics.forth.gr/isl/Ecoscope>
FROM <http://www.ics.forth.gr/isl/DBpedia>
FROM <http://www.ics.forth.gr/isl/Fishbase>
FROM <http://www.ics.forth.gr/isl/FLOD>
FROM <http://www.ics.forth.gr/isl/Worms>
FROM <http://www.ics.forth.gr/isl/Schema>
where  
{
 ?URI a <http://ics.forth.gr/Ontology/MarineTLO/imarine#MarineSpecies> .
 ?URI rdfs:label ?Value FILTER(regex(str(?Value),'<ENTITY>','i')) 
} 


REST call:

http://.../xsearch-service-2.0.0/api/link?name=salmon&category=Species


JSON result:

{
   "results": [
       {
           "Value": "Salmonidae",
           "URI": "http://dbpedia.org/resource/Salmonidae"
       },
       {
           "Value": "Sockeye salmon",
           "URI": "http://dbpedia.org/resource/Sockeye_salmon"
       },
       {
           "Value": "Chinook salmon",
           "URI": "http://dbpedia.org/resource/Chinook_salmon"
       },
       {
           "Value": "Salmon shark",
           "URI": "http://dbpedia.org/resource/Salmon_shark"
       },
       {
           "Value": "Pink salmon",
           "URI": "http://dbpedia.org/resource/Pink_salmon"
       },
       {
           "Value": "Atlantic salmon",
           "URI": "http://dbpedia.org/resource/Atlantic_salmon"
       },
       {
           "Value": "King-of-the-salmon",
           "URI": "http://dbpedia.org/resource/King-of-the-salmon"
       },
       {
           "Value": "Beaked salmon",
           "URI": "http://dbpedia.org/resource/Beaked_salmon"
       },
       {
           "Value": "Chum salmon",
           "URI": "http://dbpedia.org/resource/Chum_salmon"
       },
       {
           "Value": "Coho salmon",
           "URI": "http://dbpedia.org/resource/Coho_salmon"
       },
       {
           "Value": "Giant Salmon Carp",
           "URI": "http://dbpedia.org/resource/Giant_salmon_carp"
       },
       {
           "Value": "Giant salmon carp",
           "URI": "http://dbpedia.org/resource/Giant_salmon_carp"
       },
       {
           "Value": "Lake Salmon",
           "URI": "http://dbpedia.org/resource/Lake_Salmon"
       },
       {
           "Value": "Satsukimasu salmon",
           "URI": "http://dbpedia.org/resource/Satsukimasu_salmon"
       },
       {
           "Value": "salmonids nei",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/b254c0d9-fec2-4243-b697-1a9b76a54074"
       },
       {
           "Value": "salmonidae",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/b254c0d9-fec2-4243-b697-1a9b76a54074"
       },
       {
           "Value": "australian salmon",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/2b45d5f6-9e19-4f89-949b-de591d63723b"
       },
       {
           "Value": "salmon shrimp",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/cdf01cf9-388e-4c10-ad22-8b68bd6f9614"
       },
       {
           "Value": "salmon catfish",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/bdb5ca11-f594-4255-b6ca-5ecd792318a2"
       },
       {
           "Value": "smallmouthed salmon catfish",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/3b4729fe-4931-45dd-8683-79649d6fccc8"
       },
       {
           "Value": "salmon horse conch",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/cc3bf81f-c84e-4d7e-b391-4ad90415d1d5"
       },
       {
           "Value": "sockeye(=red)salmon",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/86021df0-f907-478b-a677-98c079466b8f"
       },
       {
           "Value": "salmonetes, etc. nep",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/ebf2099e-53cf-4b60-be70-bedb82394055"
       },
       {
           "Value": "salmonete de roca",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/d6ea3fb9-aeb2-44a7-9c9a-89a7492fc9d2"
       },
       {
           "Value": "beachsalmon",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/2af070a8-c25c-4c70-a3e5-5560f071e7c3"
       },
       {
           "Value": "salmonete de fango",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/b82bf0e5-1bbc-4f3c-b400-0392fe4c36f7"
       },
       {
           "Value": "pink(=humpback)salmon",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/46b53229-0926-42d4-b1b3-e2c233c76b9a"
       },
       {
           "Value": "salmonete vanicolense",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/942d2502-c8f1-4319-af20-5d8818643147"
       },
       {
           "Value": "chinook(=spring=king)salmon",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/9752057e-827d-40db-92fa-92bebdb53fd2"
       },
       {
           "Value": "salmonete índico",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/4490feaa-41b5-44c8-b6bc-c3c7ee83caae"
       },
       {
           "Value": "masu(=cherry) salmon",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/86b2959f-58f8-4999-b7c3-4830626754b7"
       },
       {
           "Value": "beaked salmon",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/79bb60a9-f930-4f4a-b010-144c8f3b7819"
       },
       {
           "Value": "salmonete barbudo",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/10371267-8726-4982-9155-edada05a1aab"
       },
       {
           "Value": "chum(=keta=dog)salmon",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/fb47b744-42e3-49cd-b657-4c6d7ba0753f"
       },
       {
           "Value": "atlantic salmon",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/5c909af3-c57e-4723-bef6-df6ab24fa240"
       },
       {
           "Value": "coho(=silver)salmon",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/8002f8ba-4a02-4a5f-b6f3-09dd6393ae7d"
       },
       {
           "Value": "salmon shark",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/0f7489b8-5a2c-4ca6-b3cc-aec9832e8312"
       },
       {
           "Value": "lake salmon",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/e415e0f6-4b6a-45c3-8e0f-4e1fedab81ab"
       },
       {
           "Value": "salmonoids nei",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/63f4c750-c41c-4bd0-a1a2-20f33941ba57"
       },
       {
           "Value": "salmonoideos nep",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/63f4c750-c41c-4bd0-a1a2-20f33941ba57"
       },
       {
           "Value": "salmonoidei",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/63f4c750-c41c-4bd0-a1a2-20f33941ba57"
       },
       {
           "Value": "salmonoidés nca",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/63f4c750-c41c-4bd0-a1a2-20f33941ba57"
       },
       {
           "Value": "pacific salmons nei",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/2396f893-2ef9-40ba-89f6-499a1d71d15c"
       },
       {
           "Value": "salmones del pacífico nep",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/2396f893-2ef9-40ba-89f6-499a1d71d15c"
       },
       {
           "Value": "salmonetes",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/ab76430b-3f6b-45da-8591-dfeae6d3848f"
       },
       {
           "Value": "salmonetes nep",
           "URI": "http://www.fao.org/figis/flod/entities/codedentity/8b88d794-e083-4f82-8fc4-c14ee20a4805"
       }
   ]
}

Main Service C: Enrich an identified entity

This services enriches an entity with semantic information. For example, for the entity "yellowfin tuna" (that has been linked the resource "http://dbpedia.org/resource/Yellowfin_tuna"), the service can return its incoming and outcoming properties.

Input Parameters:

  • uri - The URI of the entity (url) - required
  • type - Type of properties to retrieve (incoming|outcoming|both) - required
  • category - The category of the entity (string). If no value is given, the parameter endpoint must be specified.
  • endpoint - The SPARQL endpoint to use (url). If no value is given, the parameter category must be specified. In this case, the endpoint that has been configured in X-Search for the given category name is considered.
  • lang - The language code for retrieving literals (string)
  • format: The output format. Valid values: {json, xml, csv}. Default: json

Output:

  • A list of RDF triples

Example:

Consider that for the category "Species", the specified SPARQL endpoint is: http://virtuoso.i-marine.d4science.org:8890/sparql

REST call:

http://.../xsearch-service-2.0.0/api/enrich?uri=http://dbpedia.org/resource/Yellowfin_tuna&category=Species&type=outgoing

Part of the JSON result:

{
   "triples": [
       {
           "subject": "http://dbpedia.org/resource/Yellowfin_tuna",
           "predicate": "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
           "object": "http://dbpedia.org/ontology/Species"
       },
       {
           "subject": "http://dbpedia.org/resource/Yellowfin_tuna",
           "predicate": "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
           "object": "http://dbpedia.org/ontology/Eukaryote"
       },
       {
           "subject": "http://dbpedia.org/resource/Yellowfin_tuna",
           "predicate": "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
           "object": "http://dbpedia.org/ontology/Fish"
       },
       {
           "subject": "http://dbpedia.org/resource/Yellowfin_tuna",
           "predicate": "http://dbpedia.org/ontology/family",
           "object": "http://dbpedia.org/resource/Scombridae"
       },
       {
           "subject": "http://dbpedia.org/resource/Yellowfin_tuna",
           "predicate": "http://dbpedia.org/ontology/genus",
           "object": "http://dbpedia.org/resource/Thunnus"
       },
       {
           "subject": "http://dbpedia.org/resource/Yellowfin_tuna",
           "predicate": "http://dbpedia.org/ontology/kingdom",
           "object": "http://dbpedia.org/resource/Animal"
       },
       {
           "subject": "http://dbpedia.org/resource/Yellowfin_tuna",
           "predicate": "http://dbpedia.org/ontology/order",
           "object": "http://dbpedia.org/resource/Perciformes"
       },
       {
           "subject": "http://dbpedia.org/resource/Yellowfin_tuna",
           "predicate": "http://dbpedia.org/ontology/phylum",
           "object": "http://dbpedia.org/resource/Chordate"
       },
       {
           "subject": "http://dbpedia.org/resource/Yellowfin_tuna",
           "predicate": "http://xmlns.com/foaf/0.1/depiction",
           "object": "http://upload.wikimedia.org/wikipedia/commons/9/99/Fish4499_-_Flickr_-_NOAA_Photo_Library.jpg"
       }
   ]
}

Main Service D: Identify entities in a Web Document

This service retrieves the contents of a Web document (e.g. a Web page or a PDF file) and performs entity mining in these contents.

Input Parameters:

  • url: The URL of the Web page/document - required
  • categories: Active categories of entities (semicolon-separated names of categories) (see Supported Service S1). If no value is given, then X-Search's current active categories are considered.
  • format: The output format. Valid values: {json, xml, csv}. Default: json

Output:

  • A list with the detected entities together with their corresponding category

Example:

REST call:

http://.../xsearch-service-2.0.0/api/processdocument?url=http://en.wikipedia.org/wiki/Yellowfin_tuna&categories=Species;Country

JSON result:

{
   "identifiedEntities": [
       {
           "categoryName": "Species",
           "entityName": "yellowfin tuna"
       },
       {
           "categoryName": "Species",
           "entityName": "blackfin tuna"
       },
       {
           "categoryName": "Species",
           "entityName": "wahoo"
       },
       {
           "categoryName": "Species",
           "entityName": "striped marlin"
       },
       {
           "categoryName": "Species",
           "entityName": "Pacific bluefin tuna"
       },
       {
           "categoryName": "Species",
           "entityName": "Albacore"
       },
       {
           "categoryName": "Species",
           "entityName": "Bigeye tuna"
       },
       {
           "categoryName": "Species",
           "entityName": "Thunnus"
       },
       {
           "categoryName": "Species",
           "entityName": "Thunnus albacares"
       },
       {
           "categoryName": "Species",
           "entityName": "Dogtooth tuna"
       },
       {
           "categoryName": "Species",
           "entityName": "Frigate tuna"
       },
       {
           "categoryName": "Species",
           "entityName": "Scombridae"
       },
       {
           "categoryName": "Species",
           "entityName": "skipjack tuna"
       },
       {
           "categoryName": "Species",
           "entityName": "Atlantic bluefin tuna"
       },
       {
           "categoryName": "Species",
           "entityName": "Atlantic blue marlin"
       },
       {
           "categoryName": "Species",
           "entityName": "shark"
       },
       {
           "categoryName": "Species",
           "entityName": "flying fish"
       },
       {
           "categoryName": "Species",
           "entityName": "driftfish"
       },
       {
           "categoryName": "Species",
           "entityName": "lanternfish"
       },
       {
           "categoryName": "Species",
           "entityName": "marlin"
       },
       {
           "categoryName": "Species",
           "entityName": "black marlin"
       },
       {
           "categoryName": "Species",
           "entityName": "Little tunny"
       },
       {
           "categoryName": "Species",
           "entityName": "bonito"
       },
       {
           "categoryName": "Species",
           "entityName": "Slender tuna"
       },
       {
           "categoryName": "Species",
           "entityName": "Salmon"
       },
       {
           "categoryName": "Species",
           "entityName": "Auxis"
       },
       {
           "categoryName": "Species",
           "entityName": "Saury"
       },
       {
           "categoryName": "Species",
           "entityName": "Swordfish"
       },
       {
           "categoryName": "Species",
           "entityName": "Ilish"
       },
       {
           "categoryName": "Species",
           "entityName": "Capelin"
       },
       {
           "categoryName": "Species",
           "entityName": "Catfish"
       },
       {
           "categoryName": "Species",
           "entityName": "Shad"
       },
       {
           "categoryName": "Species",
           "entityName": "turbot"
       },
       {
           "categoryName": "Species",
           "entityName": "Flatfish"
       },
       {
           "categoryName": "Species",
           "entityName": "Haddock"
       },
       {
           "categoryName": "Species",
           "entityName": "Mullet"
       },
       {
           "categoryName": "Species",
           "entityName": "Orange roughy"
       },
       {
           "categoryName": "Species",
           "entityName": "Pollock"
       },
       {
           "categoryName": "Species",
           "entityName": "Smelt"
       },
       {
           "categoryName": "Species",
           "entityName": "Sturgeon"
       },
       {
           "categoryName": "Species",
           "entityName": "Tilapia"
       },
       {
           "categoryName": "Species",
           "entityName": "Octopus"
       },
       {
           "categoryName": "Species",
           "entityName": "Gilt-head bream"
       },
       {
           "categoryName": "Species",
           "entityName": "Thunnus alalunga"
       },
       {
           "categoryName": "Species",
           "entityName": "Perciformes"
       },
       {
           "categoryName": "Species",
           "entityName": "Thunnini"
       },
       {
           "categoryName": "Country",
           "entityName": "Mexico"
       },
       {
           "categoryName": "Country",
           "entityName": "islands"
       },
       {
           "categoryName": "Country",
           "entityName": "Panama"
       },
       {
           "categoryName": "Country",
           "entityName": "Maldives"
       },
       {
           "categoryName": "Country",
           "entityName": "Ghana"
       },
       {
           "categoryName": "Country",
           "entityName": "Costa Rica"
       },
       {
           "categoryName": "Country",
           "entityName": "U.S."
       },
       {
           "categoryName": "Country",
           "entityName": "United States"
       },
       {
           "categoryName": "Country",
           "entityName": "Taiwan"
       },
       {
           "categoryName": "Country",
           "entityName": "South Korea"
       },
       {
           "categoryName": "Country",
           "entityName": "Guinea"
       },
       {
           "categoryName": "Country",
           "entityName": "Japan"
       },
       {
           "categoryName": "Country",
           "entityName": "Canada"
       },
       {
           "categoryName": "Country",
           "entityName": "Bahamas"
       },
       {
           "categoryName": "Country",
           "entityName": "Bermuda"
       },
       {
           "categoryName": "Country",
           "entityName": "America"
       },
       {
           "categoryName": "Country",
           "entityName": "Australia"
       },
       {
           "categoryName": "Country",
           "entityName": "New Zealand"
       },
       {
           "categoryName": "Country",
           "entityName": "England"
       },
       {
           "categoryName": "Country",
           "entityName": "South Africa"
       },
       {
           "categoryName": "Country",
           "entityName": "Indonesia"
       },
       {
           "categoryName": "Country",
           "entityName": "Saudi Arabia"
       },
       {
           "categoryName": "Country",
           "entityName": "Nauru"
       }
   ]
}

Support Service S1: Get the supported categories of entities

This service returns the categories that are currently supported by XSearch-Service. The service also returns the SPARQL endpoint and the SPARQL template query that have been defined for each category.

Input Parameters:

- format: The output format. Valid values: {json, xml, csv}. Default: json

Output:

  • The names of the supported categories and for each category the corresponding SPARQL endpoint and template query


Example:

REST call:

http://..../xsearch-service-2.0.0/api/getsupportedcategories

JSON Result:

{
   "categories": [
       {
           "categoryName": "Regional_Fisheries_Body",
           "templateQuery": "SELECT DISTINCT ?RFB ?URI WHERE ... ... ...",
           "endpoint": "http://virtuoso.i-marine.d4science.org:8890/sparql?query="
       },
       {
           "categoryName": "Country",
           "templateQuery": "SELECT DISTINCT ?URI ?Country WHERE ... ... ...",
           "endpoint": "http://virtuoso.i-marine.d4science.org:8890/sparql?query="
       },
       {
           "categoryName": "Species",
           "templateQuery": "SELECT DISTINCT ?URI ?Species WHERE ... ... ...",
           "endpoint": "http://virtuoso.i-marine.d4science.org:8890/sparql?query="
       },
       {
           "categoryName": "Water_Area",
           "templateQuery": "SELECT DISTINCT ?URI ?WaterArea WHERE ... ... ...",
           "endpoint": "http://virtuoso.i-marine.d4science.org:8890/sparql?query="
       }
   ]
}

Support Service S2: Get the supported clustering algorithms

This service returns the algorithms that are supported bt XSearch-Service.

Input Parameters:

- format: The output format. Valid values: {json, xml, csv}. Default: json

Output:

  • The ID and a small description for each supported clustering algorithm


Example:

REST call:

http://.../xsearch-service-2.0.0/api/getsupportedclusteringalgs

JSON Result:

{
   "supportedClusteringAlgorithms": [
       {
           "id": "cl5",
           "description": "NM-STC+: Variation of NM-STC"
       },
       {
           "id": "cl3",
           "description": "NM-STC: No Merge Suffix Tree Clustering (http://users.ics.forth.gr/~tzitzik/publications/Tzitzikas_2009_WISE.pdf)"
       },
       {
           "id": "cl4",
           "description": "STC++: Variation of STC+"
       },
       {
           "id": "cl1",
           "description": "STC: Suffix Tree Clustering Algorithm"
       },
       {
           "id": "cl2",
           "description": "STC+: Variation of STC which differs in the way the clusters are scored and in the way base clusters are merged (http://users.ics.forth.gr/~tzitzik/publications/Tzitzikas_2009_WISE.pdf)"
       }
   ]
}

Support Service S3: Get the supported search systems

This service returns the search systems that are currently supported by X-Search-Service.

Input Parameters:

- format: The output format. Valid values: {json, xml, csv}. Default: json

Output:

  • The name and a small description of each supported search system

Example:

REST call:

http://.../xsearch-service-2.0.0/api/getsupportedsearchsystems

JSON Result:

{
   "supportedSearchSystems": [
       {
           "description": "Ecoscope Search System (http://www.ecoscopebc.ird.fr/)",
           "name": "ecoscope"
       },
       {
           "description": "OpenSearch (http://www.opensearch.org/). The OpenSearch Description Document must be provided.",
           "name": "opensearch"
       },
       {
           "description": "gCube Infrastructure Search System (https://i-marine.d4science.org/web/guest/about-gcube). The ResultSet locator must be provided.",
           "name": "gcube"
       }
   ]
}