Specifications for the Output Web Services

From wiki.gpii
Jump to: navigation, search

Output Web services specs

Version 2.1

To provide data retrieved by the EASTIN search engine to the GPII Unified Listing, a specific set of Web Services has been implemented that contains functions to extract data using the EASTIN search engine. These Output Web Services Servers are exposed by the EASTIN search engine and will be accessed by a specific application (Output Web Service Client) aimed at collecting the data retrieved from EASTIN into the GPII Unified Listing database.

The output Web Services are based on a RESTful architecture and the response is provided in JSON format.

Two methods are provided:

- FindProductsSortBySimilarity: returns a list of products including basic information

- GetProduct: returns detailed information of a specific product

Method FindProductsSortBySimilarity

{BasicProductInfoDto[] Records, bool Ok, string[] ExceptionMessages} FindProductsSortBySimilarity (string isoCodes, string commercialName, string manufacturer, string insertDateMin, string insertDateMax, string baseForSimilarity, string features, string lastUpdateMin)

This method is used to search for products in the databases of the EASTIN network according to the specified parameters. The method returns an array of “BasicProductInfoDto” ("Records") including the basic product information (see EASTIN Custom Data Type paragraph for details) and two additional fields ("Ok", "ExeptionMessages") describing possible exeptions occured.


This method can be accessed at the url: http://webservices.eastin.eu/cloud4allwebapi/searches/products/listsimilarity.

The template for the input parameters is the following:

"/products/listsimilarity?isoCodes={isoCodes}&commercialName={commercialName}&manufacturer={manufacturer}&insertDateMin={insertDateMin}&insertDateMax={insertDateMax}&baseForSimilarity={baseForSimilarity}&features={features}&lastUpdateMin={lastUpdateMin}"

Example: http://webservices.eastin.eu/cloud4allwebapi/searches/products/listsimilarity?isoCodes=223618&commercialName=dra&insertDateMin=2012-01-01


Input parameters:

-      string isoCodes: a string representing the ISO 9999 codes of the products to be searched. Each code must be written without separators (i.e. 223618, not 22.36.18). Separator among different codes is “-” (e.g. “223618-223612”).

-      string commercialName: the whole or a part of the commercial name of the products to be searched;

-      string manufacturer: the whole or a part of the manufacturer name of the products to be searched;

-      string insertDateMin: the lower bound for the insert date of the products to be searched. Insert date must be written in the format: “yyyy-mm-ddThh:mm”

-      string insertDateMax: the upper bound for the insert date of the products to be searched. Insert date must be written in the format: “yyyy-mm-ddThh:mm”

-      string baseForSimilarity: this parameter identifies the product that has to be taken as base for similarity. The product to be taken as base for similarity is identified by a string that concatenates database name and product code (e.g. "siva18971", "dlf data0110572", etc.). <note: in the previous version the parameter was an integer number that represented the position of the product in the result list when no base for similarity is specified (0 is the first position)>

-      string features: a string representing the IDs of the features of the products to be searched. Each feature ID can be followed by a “_” and the minimum and maximum value to be searched separated by “_” (for example the feature “length (cm)” has ID=3, if I want to search devices that have length between 10 and 20 cm the string will be: “3_10_20” ). Separator among different feature is “-”  (for example a complete features string could be: “3_10_20-4_5_15”. This means search for products that have a “length (cm)” (id=3) between 10 and 20, and a “height (cm)” between 5 and 15). For the complete vocabulary of Features see the Annex 1 of deliverable 203.1 The vocabulary of the EASTIN taxonomy.

-    string lastUpdateMin the lower bound for the last update date of the products to be searched. Dates must be written in the format: “yyyy-mm-ddThh:mm”. WARNING: this is a post-filtering parameter, it can not be used alone for searching records, it must be used in combination with other input parameters.

Returns:

  • BasicProductInfoDto[] Records: array of BasicProductInfoDto objects, each containing a light set of information about a product (for a complete description of the BasicProductInfoDto object see EASTIN Custom Data Type paragraph). If no product is found returns a not null BasicProductInfoDto[] array with zero elements. If the parameter baseForSimilarity is specified, products are sorted according to the similarity with the product selected as base for comparison.
  • Bool OK: this value is true if no exeptions has occured. If the value is false at least one exeption has been returned by one of the EASTIN databases.
  • String[] ExceptionMessages: an array containing the exception messagges (if any).

For the purpose of the Unified Listing the most important input parameter is “isoCodes”. A list of ISO codes relevant for the ICT field is available at the page:  Specifications_of_the_Unified_Listing

This method returns an array of objects belonging to the class BasicProductInfoDto. The method implements five different kinds of searches:

  1. If the isoCodes string is not void the method searches for all products belonging to the ISO classes passed, using an OR statement. For example if “223618-223612” is the isoCodes string, all products belonging to the 223618 ISO class OR to the 223612 class are returned.
  2. If commercialName is not void the method searches a matching between the words contained in the  commercialName parameter and the respective data in the EASTIN partner’s local database. Since into the commercialName parameter there could be one or more words, the method must split the words and search inside its database for products whose commercial name contains all these words (even if present as substrings inside of biggest strings). For example if commercialName = “quickie xenon” the method must search for all products whose commercial name contains both words “quickie” AND “xenon”.
  3. If manufacturer is not void the method executes the search using the same criteria specified in 2 but applied to products’ manufacturer name.
  4. If insertDateMin and insertDateMax are both not void all products whose insert date is included within the interval [insertDateMin, insertDateMax], endpoints included, are returned.
  5. If features is not void all products whose feature are specified are returned. The feature parameter is a string representing the IDs of the features of the products to be searched. Each feature ID can be followed by a “_” and the minimum and maximum value to be searched separated by “_” (for example the feature “length (cm)” has ID=3, if I want to search devices that have length between 10 and 20 cm the string will be: “3_10_20” ). Separator among different feature is “-”  (for example a complete features string could be: “3_10_20-4_5_15”. This means search for products that have a “length (cm)” (id=3) between 10 and 20, and a “height (cm)” between 5 and 15).

 If more than one parameter is not void at the same time, the results coming from the matches for each parameter are merged together with an AND logic: only results satisfying the conditions specified for each parameter are returned. If no product is found the method returns a not null BasicProductInfoDto[] array with zero elements. If the parameter baseForSimilarity is specified, products are sorted according to the similarity with the product selected as base for comparison

If the parameter lastUpdateMin is specified a filtering of results is made (after the results have been retrieved from the databases) so that only products updated after the specified date are returned

Method GetProduct

{ProductDetailsDto Recordbool Okstring ExceptionMessage} GetProduct(string database, string productCode);

This method is used get the detailed description of a specific product in one of the databases of the EASTIN network. The method returns an object belonging to the class “ProductDetailsDto” (see EASTIN Custom Data Type paragraph for details).


This method can be accessed at the url:  http://webservices.eastin.eu/cloud4allwebapi/searches/products/detail.

The template for the input parameters is the following:

"/products/detail?database={database}&productCode={productCode}"


Input parameters:

-      string database: the name of the database where the product record is stored

-      string productCode: a string representing the unique ID in the specified database

Returns:

  • ProductDetailsDto Record: an object containing detailed description of a single product. If no product is found a null object is returned.
  • Bool OK: this value is true if no exeptions has occured. 
  • String ExceptionMessage: the exception messagge (if any).

This method returns an object belonging to the class ProductDetailsDto (for a complete description of the ProductDetailsDto object see below). The method searches into the EASTIN partner’s local database, specified in the parameter “database”, for the product which has the id matching with the parameter “productCode”. If no product is found the method returns the null object.


Custom data types

EASTIN Output Web services return custom defined types. A complete description of EASTIN custom defined types follows below. All mandatory fields are marked with a “*” (all the other fields can be considered as nullable). For the array fields in case they are empty a not null array of zero elements is returned.


BasicProductInfoDto:

  • string Database*: the name of the database where the product record comes from 
  • string ProductCode*: the id of the product in the partner’s local database
  • IsoNodeDto IsoCodePrimary*: Custom data type (see below) representing the Primary ISO 9999 classification code for the product
  • IsoNodeDto[] IsoCodesOptional: the array of all secondary ISO 9999 classification codes of the product
  • string CommercialName*: the name of the product
  • string ManufacturerOriginalFullName*: the full name in the original language of the product’s manufacturer
  • DateTime InsertDate*: the insert date of the product;
  • DateTime LastUpdateDate*: the last update date of the product;
  • string ThumbnailImageUrl: the URL of the small format picture of the product (used when displaying list of products in EASTIN Portal).
  • string SimilarityLevel: the level of similarity of the current product with the product selected as base for comparison. (For more information about the similarity concept and the algorithm to evaluate similarity see the wiki page Algorithm_for_product_similarity )


ProductDetailsDto:

  • string Database*: the name of the database where the product record comes from 
  • string ProductCode*: the id of the product in the partner’s local database
  • IsoNodeDto IsoCodePrimary*: Custom data type (see below) representing the Primary ISO 9999 classification code for the product
  • IsoNodeDto[] IsoCodesOptional: the array of all secondary ISO 9999 classification codes of the product
  • string CommercialName*: the name of the product
  • string ManufacturerOriginalFullName*: the full name in the original language of the product’s manufacturer
  • string ManufacturerAddress: the address of the product’s manufacturer;
  • string ManufacturerPostalCode: the postal code of the product’s manufacturer;
  • string ManufacturerTown: the town of the product’s manufacturer;
  • string ManufacturerCountry*: the country code of the product’s manufacturer according to the two letter ISO standard 3166-1-alpha-2 code (for example “IT”, “US”, etc.);
  • string ManufacturerPhone: the phone of the product’s manufacturer;
  • string ManufacturerEmail: the email of the product’s manufacturer;
  • string ManufacturerWebSiteUrl : the Web site URL of the product’s manufacturer;
  • DateTime InsertDate*: the insert date of the product;
  • DateTime LastUpdateDate*: the last update date of the product;
  • string ThumbnailImageUrl: the URL of the small format picture of the product (used when displaying list of products in EASTIN Portal).
  • string ImageUrl the URL of the big format image of the product (used when displaying the detail view of the product in the EASTIN portal).
  • string EnglishDescription: the description of the product in English;
  • string OriginalUrl: the URL of the Web page in the original language on the original EASTIN partner’s Web site in which the product is presented. The URL must be accessible on the Web by the end user’s browser;
  • string EnglishUrl: the URL of the Web page in English on the original EASTIN partner’s Web site in which the product is presented. The URL must be accessible on the Web by the end user’s browser;
  • FeatureWithNameDto[] Features : an array of FeatureWithNameDto objects (see the custom data type below) containing the product features according to the EASTIN Taxonomy.


IsoNodeDto

  • string Code: the numeric code of the ISO 9999 item (e.g. “223618”)
  • string Name: the name of the ISO 9999 item (e.g. “Input devices”)


FeatureWithNameDto:

  • int FeatureId: the ID of the feature in the ETNA taxonomy
  • string FeatureName: the name of the feature according to the ETNA taxonomy (e.g. “Weight (Kg)”)
  • string FeatureParentName: the name of the “cluster” the feature belongs to (e.g. “Overall dimensions”)
  • decimal ValueMin: for features that can have an associated numeric value (e.g. “Magnification”), is the minimum value of the feature for the specific product
  • decimal ValueMax: for features that can have an associated numeric value (e.g. “Magnification”), is the maximum value of the feature for the specific product


<a href="#_ftnref1">[1]</a> For the complete set of feature IDs see Annex 1: The vocabulary of the EASTIN taxonomy

<a href="#_ftnref2">[2]</a> For more information about the similarity concept and the algorithm to evaluate similarity see Algorithm for product similarity

Wiki Categories