Overview

The Goldfire API enables developers to use API calls to access the following capabilities of Goldfire:

Run queries against specific knowledge bases.
Get citations.
Filter results by metacategory, category, fact,...
Filter results by applying facets.
Get a list of all the knowledge bases.
Get information about the corporate knowledge bases where specific documents are indexed.
Browse and view categories of data that are contained in knowledge bases.
Remove ambiguities from queries.
Get summaries of documents that are returned in a query.
Get a list of synonyms for a query.
Get a list of query type-ahead search (QTA) search and query refinement suggestions.
Export results.

See here for detailed descriptions of how to use the Goldfire API calls.

The Goldfire API is a web API that uses REST technology.
API calls return data in either JSON or XML formats.
Each resource in the Goldfire API is a named URI that uses one of the following HTTP methods:

POST
GET
PUT
DELETE

Getting Started

To begin working with the Goldfire API, you must have an application key and a security token.

The application key can be retrieved from this file: <Goldfire>\HTML\IM.Goldfire.Server\App_Data\Api.key. <Goldfire> - goldfire installation folder.
The security token is returned by the last successful api/Login call (see the example below or refer to documentation about the login process).

The Goldfire API uses the following URI template:

http[s]://<goldfire_services_url>/api/<resource>

<Goldfire_services_url> is the URL for the Goldfire web services (virtual root path).
<resource> refers to the API method like search.

The Goldfire API returns standard HTTP status codes.

Using the Goldfire API

In order to access the API, you must have an application key and security token. Use the next call to obtain the security token.

POST http[s]://<goldfire_services_url>/api/login

Input package:

						
Headers:
						Content-Type: application/json
						api-key: "application key"
Body:
{
  "Name": "Test_name",
  "Password": "Test_password"
}

Output package:

 
{
  "SecurityToken": "string"
}

See here for more details about the login process.

Now you have access to the Goldfire API.

Performing a simple search:

Use the search API method.

First, determine the knowledge bases available for the query.

GET http[s]://<goldfire_services_url>/api/KnowledgeBase/nodes/|1

Input package:

					
Headers:
					Content-Type: application/json
					api-key: "application key"
					sid: "security token"

Output package:

					
{
  [
   {
     Id:4,3|1,
     Name: Patents,
    ...
   },
  ...
  ]
}

The output package contains the knowledge base tree. Each knowledge base and knowledge base category has an identifier and a name. Use these identifiers in the search.
See here for details about the knowledge base tree. Performing the search:

POST http[s]://<goldfire_services_url>/api/researcher

Input package:

					
Headers:
  Content-Type: application/json  
    api-key: "application key"
    sid: "security token"
Body:
{
  "Expression": "how to reduce cholesterol?",
  "Language": 1033,
  "ExpressionType": 4,
  "KnowledgeBases": ["4,3|1"]
}

Output package:

					
{
  "Citations":{
  "Items":[...],
  "Facets": [...],
    ...
  },
  "Lenses":{
    Items:[...]},
  "Log":{...}
}

This request performs a simple search with a minimal set of parameters.
Expression: The query for the search.
Language: The query language (1033 - English).
ExpressionType: The query semantic type. (Set ExpressionType to 4 to perform most searches.)
KnowledgeBases: Where to search (see previous step).

The output package contains information about document citations and document metadata fields.

Using the api/researcher endpoint, you can also perform complex searches. For example, you can filter search results by applying facets to the above search.

Input package:

						
Headers:
  ...
Body:
{
  ...,
						"NumberFacetRangeFilters":[{"Id":"F_DP","From":1980,"To":2005,"IncludeMissed":false}]
}

In this example, the results are filtered by a date range ("F_DP").
The IncludeMissed option will exclude documents that do not fall within this range. See here for details about this method and these parameters.

The first ten search results are returned by default. A maximum of 200 results can be returned.
You can browse all the search results by setting the page filter. For this purpose, use api/citations

POST http[s]://<goldfire_services_url>/api/citations

Input package:

						
Headers:
    Content-Type: application/json  
    api-key: "application key"
    sid: "security token"
Body:
{
  "Expression": "how to reduce cholesterol?",
  "Language": 1033,
  "ExpressionType": 4,
  "KnowledgeBases": ["4,3|1"],
						"CState": { "Page": [{ "Count":100, "From":2 }] }
}

See details here.

Additional examples

See below for more examples of using the Goldfire API:

- Browse by meta-categories.

POST http[s]://<goldfire_services_url>/api/lenses

Input package:

					
Headers:
  ...
Body:
{
  "Expression": "how to reduce cholesterol?",
  "Language": 1033,
  "ExpressionType": 4,
  "KnowledgeBases": ["4,3|1"],
					"LState":{"MetaId":2,"ConceptId":1}
}

Output package:

					
{
  Lenses:
    {
      Items:[]
      ...

    },
    Log:{}
}

A response from the api/researcher returns a list of available meta-categories (MetaId) and concepts (ConceptId).
The output contains a list of lenses related to the meta-category with answers. The maximum number of returned answers is 200.
See here for details.

- Viewing a document summary.

POST http[s]://<goldfire_services_url>/api/summaryuni

Input package:

					
Headers:
  ...
Body:
{
  "DocumentId": "4,1001,1|87593010|1033|3"
}

Output package:

					
{
  DocId: "Full document id",
  Items:[],
  ....
}

The document identifier must be included to retrieve the document summary. The output contains information about documents presented as a list of summary fields.
See here for details.

- Query Type Ahead (QTA).

When users type a query, Goldfire provides suggestions based on indexed content and on a user’s previous queries. Goldfire also suggests corrections for typographical errors, missing spaces, etc. Users can select from the list of displayed suggestions.

POST http[s]://<goldfire_services_url>/api/QueryTypeAhead

Input package:

					
Headers:
  ...
Body:
{
  "Query":"las",
  "Scope":{"Items":[{"Id":"4,4|1","Type":1}]},
  "Language":1033,
  "CurrentPosition":3
}

Output package:

					
{
  "RecentLines": [{
    "Id": 170253,
    "Line": [{
      "Tag": null,
      "Text": "laser   laser"
    }],
    "DocumentTypes": null,
    "FieldId": null,
    "Prefix": null
  }
  ...
  ],
  "SuggestionLines": [{
    "Line": [{
      "Tag": null,
      "Text": "las"
    },
    {
      "Tag": "c",
      "Text": "er beam"
    }],
    "DocumentTypes": null,
    "FieldId": "FTXT",
    "Prefix": null,
    "KbIds": []
  }
  ...
  ],
  "TokenIndent": 0,
  "TokenLength": 3
}

The input package contains the following:
Query: The text for which suggestions are necessary.
Scope: The scope is the knowledge bases in which the search is performed. These knowledge bases are the ones from which results are returned.
Language: The query language.
CurrentPosition: The position of the cursor in the query string at the instance a request is sent.

The output package contains the following:
RecentLines: Lines that define the query type-ahead suggestions related to recent user searches.
SuggestionLines: Lines that define query type-ahead suggestions selected from knowledge base content.
TokenIndent: Defines the value of shift (in characters) relative to the whole query. If the value is greater than zero, you must shift the list of suggestions.
TokenLength: Defines the number of characters in the original query that will be replaced by the suggestion, starting from the TokenIndent value.

See here for details. See here for an example of the simple JS App that uses Goldfire API without external authentication. . See here for an example of the simple JS App that uses Goldfire API with external authentication.