response, IBMError error) =>\n {\n Log.Debug(\"NaturalLanguageUnderstandingServiceV1\", \"Analyze result: {0}\", response.Response);\n },\n url: \"www.ibm.com\",\n features: features\n);\n```\n\nReturns high-level concepts in the content. For example, a research paper about deep learning might return the concept, \"Artificial Intelligence\" although the term is not mentioned.\n\n#### Concepts request options\n\n\n
\n
\n
Request options
\n ConceptsOptions\n \n
\n
\n
For more information, see the request body for the Analyze text method.
\n
\n
\n
\n
\n
Apples and Oranges
I love apples! I don't like oranges.
\",\n \"features\": {\n \"emotion\": {\n \"targets\": [\n \"apples\",\n \"oranges\"\n ]\n }\n }\n}\n```\n\n```go\npackage main\n\nimport (\n \"encoding/json\"\n \"fmt\"\n \"github.com/IBM/go-sdk-core/core\"\n \"github.com/watson-developer-cloud/go-sdk/naturallanguageunderstandingv1\"\n)\n\nfunc main() {\n authenticator := &core.IamAuthenticator{\n ApiKey: \"{apikey}\",\n }\n\n options := &naturallanguageunderstandingv1.NaturalLanguageUnderstandingV1Options{\n Version: \"2022-04-07\",\n Authenticator: authenticator,\n }\n\n naturalLanguageUnderstanding, naturalLanguageUnderstandingErr := naturallanguageunderstandingv1.NewNaturalLanguageUnderstandingV1(options)\n\n if naturalLanguageUnderstandingErr != nil {\n panic(naturalLanguageUnderstandingErr)\n }\n\n naturalLanguageUnderstanding.SetServiceURL(\"{url}\")\n\n html := \"FruitsApples and Oranges
I love apples! I don't like oranges.
\"\n targets := []string{\"apples\", \"oranges\"}\n\n response, responseErr := naturalLanguageUnderstanding.Analyze(\n &naturallanguageunderstandingv1.AnalyzeOptions{\n HTML: &html,\n Features: &naturallanguageunderstandingv1.Features{\n Emotion: &naturallanguageunderstandingv1.EmotionOptions{\n Targets: targets,\n },\n },\n },\n )\n if responseErr != nil {\n panic(responseErr)\n }\n b, _ := json.MarshalIndent(result, \"\", \" \")\n fmt.Println(string(b))\n}\n```\n\nExample Emotion feature request\n\n```java\nIamAuthenticator authenticator = new IamAuthenticator(\"{apikey}\");\nNaturalLanguageUnderstanding naturalLanguageUnderstanding = new NaturalLanguageUnderstanding(\"2022-04-07\", authenticator);\nnaturalLanguageUnderstanding.setServiceUrl(\"{url}\");\n\nString html = \"Fruits\" +\n \"Apples and Oranges
\" +\n \"I love apples! I don't like oranges.
\" +\n \"\";\n\nList targets = new ArrayList<>();\ntargets.add(\"apples\");\ntargets.add(\"oranges\");\n\nEmotionOptions emotion= new EmotionOptions.Builder()\n .targets(targets)\n .build();\n\nFeatures features = new Features.Builder()\n .emotion(emotion)\n .build();\n\nAnalyzeOptions parameters = new AnalyzeOptions.Builder()\n .html(html)\n .features(features)\n .build();\n\nAnalysisResults response = naturalLanguageUnderstanding\n .analyze(parameters)\n .execute()\n .getResult();\nSystem.out.println(response);\n```\n\nExample Emotion feature request\n\n```javascript\nconst NaturalLanguageUnderstandingV1 = require('ibm-watson/natural-language-understanding/v1');\nconst { IamAuthenticator } = require('ibm-watson/auth');\n\nconst naturalLanguageUnderstanding = new NaturalLanguageUnderstandingV1({\n version: '2022-04-07',\n authenticator: new IamAuthenticator({\n apikey: '{apikey}',\n }),\n serviceUrl: '{url}',\n});\n\nconst analyzeParams = {\n 'html': 'FruitsApples and Oranges
I love apples! I don\\'t like oranges.
',\n 'features': {\n 'emotion': {\n 'targets': [\n 'apples',\n 'oranges'\n ]\n }\n }\n};\n\nnaturalLanguageUnderstanding.analyze(analyzeParams)\n .then(analysisResults => {\n console.log(JSON.stringify(analysisResults, null, 2));\n })\n .catch(err => {\n console.log('error:', err);\n });\n```\n\nExample Emotion feature request\n\n```python\nimport json\nfrom ibm_watson import NaturalLanguageUnderstandingV1\nfrom ibm_cloud_sdk_core.authenticators import IAMAuthenticator\nfrom ibm_watson.natural_language_understanding_v1 \\\n import Features, EmotionOptions\n\nauthenticator = IAMAuthenticator('{apikey}')\nnatural_language_understanding = NaturalLanguageUnderstandingV1(\n version='2022-04-07',\n authenticator=authenticator\n)\n\nnatural_language_understanding.set_service_url('{url}')\n\nresponse = natural_language_understanding.analyze(\n html=\"FruitsApples and Oranges
I love apples! I don't like oranges.
\",\n features=Features(emotion=EmotionOptions(targets=['apples','oranges']))).get_result()\n\nprint(json.dumps(response, indent=2))\n```\n\nExample Emotion feature request\n\n```ruby\nrequire \"json\"\nrequire \"ibm_watson/authenticators\"\nrequire \"ibm_watson/natural_language_understanding_v1\"\ninclude IBMWatson\n\nauthenticator = Authenticators::IamAuthenticator.new(\n apikey: \"{apikey}\"\n)\n\nnatural_language_understanding = NaturalLanguageUnderstandingV1.new(\n version: \"2022-04-07\",\n authenticator: authenticator\n)\nnatural_language_understanding.service_url = \"{url}\"\n\nresponse = natural_language_understanding.analyze(\n html: \"FruitsApples and Oranges
I love apples! I don't like oranges.
\",\n features: {emotion: {targets: ['apples','oranges']}}\n)\n\nputs JSON.pretty_generate(response.result)\n```\n\nExample Emotion feature request\n\n```swift\nlet authenticator = WatsonIAMAuthenticator(apiKey: \"{apikey}\")\nlet naturalLanguageUnderstanding = NaturalLanguageUnderstanding(version: \"2022-04-07\", authenticator: authenticator)\nnaturalLanguageUnderstanding.serviceURL = \"{url}\"\n\nlet html = \"Fruits\" +\n \"Apples and Oranges
\" +\n \"I love apples! I don't like oranges.
\" +\n \"\"\nlet emotion = EmotionOptions(targets: [\"apples\", \"oranges\"])\nlet features = Features(emotion: emotion)\nnaturalLanguageUnderstanding.analyze(features: features, html: html) {\n response, error in\n\n guard let analysis = response?.result else {\n print(error?.localizedDescription ?? \"unknown error\")\n return\n }\n\n print(analysis)\n}\n```\n\nExample Emotion feature request\n\n```cs\nIamAuthenticator authenticator = new IamAuthenticator(\n apikey: \"{apikey}\"\n );\n\nNaturalLanguageUnderstandingService naturalLanguageUnderstanding = new NaturalLanguageUnderstandingService(\"2022-04-07\", authenticator);\nnaturalLanguageUnderstanding.SetServiceUrl(\"{url}\");\n\nvar result = naturalLanguageUnderstanding.Analyze(\n html: \"FruitsApples and Oranges
I love apples! I don't like oranges.
\",\n features: new Features()\n {\n Emotion = new EmotionOptions()\n {\n Targets = new List { \"apples\", \"oranges\" }\n }\n }\n );\n\nConsole.WriteLine(result.Response);\n```\n\nExample Emotion feature request\n\n```cs\nIamAuthenticator authenticator = new IamAuthenticator(\n Apikey: \"{apikey}\"\n);\n\nwhile (!authenticator.CanAuthenticate())\n yield return null;\nNaturalLanguageUnderstandingService service = new NaturalLanguageUnderstandingService(\"2022-04-07\", authenticator);\n\nFeatures features = new Features()\n{\n Emotion = new EmotionOptions()\n {\n Targets = {\"apples\",\"oranges\"}\n }\n};\n\nnaturalLanguageUnderstanding.Analyze(\n callback: (DetailedResponse response, IBMError error) =>\n {\n Log.Debug(\"NaturalLanguageUnderstandingServiceV1\", \"Analyze result: {0}\", response.Response);\n },\n html: \"FruitsApples and Oranges
I love apples! I don't like oranges.
\",\n features: features\n);\n```\n\nDetects anger, disgust, fear, joy, or sadness that is conveyed in the content or by the context around target phrases specified in the targets parameter. You can analyze emotion for detected entities with `entities.emotion` and for keywords with `keywords.emotion`.\n\n#### Emotion request options\n\n\n
\n
\n
Request options
\n EmotionOptions\n \n
\n
\n
For more information, see the request body for the Analyze text method.
\n
\n
\n
\n
\n
\n
\n
\n
Request options
\n EntitiesOptions\n \n
\n
\n
For more information, see the request body for the Analyze text method.
\n
\n
\n
\n
\n - \n
\n
entities.limit
\n integer\n int\n long\n \n \n
Maximum number of entities to return.
\n
\n Default: \n 50\n
\n
\n - \n
\n
entities.mentions
\n boolean\n bool\n \n \n
Whether to return locations of entity mentions.
\n
\n Default: \n false\n
\n
\n - \n
\n
entities.model
\n string\n str\n \n \n
A custom model ID. For more information about how to override the standard entity detection model, see Customizing\n
\n
\n - \n
\n
entities.sentiment
\n boolean\n bool\n \n \n
Whether to return sentiment information for detected entities.
\n
\n Default: \n false\n
\n
\n - \n
\n
entities.emotion
\n boolean\n bool\n \n \n
Whether to return emotion information for detected entities.
\n
\n Default: \n false\n
\n
\n
\n
\n
\n
\n
Request options
\n KeywordsOptions\n \n
\n
\n
For more information, see the request body for the Analyze text method.
\n
\n
\n
\n
\n - \n
\n
keywords.limit
\n integer\n int\n long\n \n \n
Maximum number of keywords to return.
\n
\n Default: \n 50\n
\n
\n - \n
\n
keyword.sentiment
\n boolean\n bool\n \n \n
Whether to return sentiment information for detected keywords.
\n
\n Default: \n false\n
\n \n
\n - \n
\n
keyword.emotion
\n boolean\n bool\n \n \n
Whether to return emotion information for detected keywords.
\n
\n Default: \n false\n
\n
\n
\n
\n
No request parameters
\n
This feature does not accept any request options.
\n
\n
\n
\n
Request options
\n RelationsOptions\n \n
\n
\n
For more information, see the request body for the Analyze text method.
\n
\n
\n
\n
\n
\n
\n
\n
Request options
\n SemanticRolesOptions\n \n
\n
\n
For more information, see the request body for the Analyze text method.
\n
\n
\n
\n
\n - \n
\n
semantic_roles.limit
\n integer\n int\n long\n \n \n
Maximum number of semantic_roles results to return.
\n
\n Default: \n 50\n
\n
\n - \n
\n
semantic_roles.keywords
\n boolean\n bool\n \n \n
Whether to return keyword information for subjects and objects.
\n
\n Default: \n false\n
\n
\n - \n
\n
semantic_roles.entities
\n boolean\n bool\n \n \n
Whether to return entity information for subjects and objects.
\n
\n Default: \n false\n
\n
\n
\n
\n
\n
\n
Request options
\n SentimentOptions\n \n
\n
\n
For more information, see the request body for the Analyze text method.
\n
\n
\n
\n
\n
\n
\n
\n
Request options
\n SyntaxOptions\n \n
\n
\n
For more information, see the request body for the Analyze text method.
\n
\n
\n
\n
\n
\n
\n
\n
Request options
\n SummarizationOptions\n \n
\n
\n
For more information, see the request body for the Analyze text method.
\n
\n
\n
\n
\n
integer | The HTTP response code. |\n| **error**
string | General description of an error. |\n\nThe Java SDK generates an exception for any unsuccessful method invocation. All methods that accept an argument can also throw an `IllegalArgumentException`.\n\n| Exception | Description |\n|------------------------------|-----------------------------------------------|\n| **IllegalArgumentException** | An invalid argument was passed to the method. |\n\nWhen the Java SDK receives an error response from the Natural Language Understanding service, it generates an exception from the `com.ibm.watson.developer_cloud.service.exception` package. All service exceptions contain the following fields.\n\n| Field | Description |\n|----------------|------------------------------------------|\n| **statusCode** | The HTTP response code that is returned. |\n| **message** | A message that describes the error. |\n\nExample error handling\n\n```java\ntry {\n // Invoke a method\n} catch (NotFoundException e) {\n // Handle Not Found (404) exception\n} catch (RequestTooLargeException e) {\n // Handle Request Too Large (413) exception\n} catch (ServiceResponseException e) {\n // Base class for all exceptions caused by error responses from the service\n System.out.println(\"Service returned status code \"\n + e.getStatusCode() + \": \" + e.getMessage());\n}\n```\n\nWhen the Node SDK receives an error response from the Natural Language Understanding service, it creates an `Error` object with information that describes the error that occurred. This error object is passed as the first parameter to the callback function for the method. The contents of the error object are as shown in the following table.\n\n**Error**\n\n| Field | Description |\n|-------------|------------------------------------------|\n| **code** | The HTTP response code that is returned. |\n| **message** | A message that describes the error. |\n\nExample error handling\n\n```javascript\nnaturalLanguageUnderstanding.method(params)\n .catch(err => {\n console.log('error:', err);\n });\n```\n\nThe Python SDK generates an exception for any unsuccessful method invocation. When the Python SDK receives an error response from the Natural Language Understanding service, it generates an `ApiException` with the following fields.\n\n| Field | Description |\n|-------------|---------------------------------------------------------|\n| **code** | The HTTP response code that is returned. |\n| **message** | A message that describes the error. |\n| **info** | A dictionary of additional information about the error. |\n\nExample error handling\n\n```python\nfrom ibm_watson import ApiException\ntry:\n # Invoke a method\nexcept ApiException as ex:\n print \"Method failed with status code \" + str(ex.code) + \": \" + ex.message\n```\n\nWhen the Ruby SDK receives an error response from the Natural Language Understanding service, it generates an `ApiException` with the following fields.\n\n| Field | Description |\n|-------------|---------------------------------------------------------|\n| **code** | The HTTP response code that is returned. |\n| **message** | A message that describes the error. |\n| **info** | A dictionary of additional information about the error. |\n\nExample error handling\n\n```ruby\nrequire \"ibm_watson\"\nbegin\n # Invoke a method\nrescue IBMWatson::ApiException => ex\n print \"Method failed with status code #{ex.code}: #{ex.error}\"\nend\n```\n\nThe Go SDK generates an error for any unsuccessful service instantiation and method invocation. You can check for the error immediately. The contents of the error object are as shown in the following table.\n\n**Error**\n\n| Field | Description |\n|-------------|------------------------------------------|\n| **code** | The HTTP response code that is returned. |\n| **message** | A message that describes the error. |\n\nExample error handling\n\n```go\nimport \"github.com/watson-developer-cloud/go-sdk/naturallanguageunderstandingv1\"\n\n// Instantiate a service\nnaturalLanguageUnderstanding, naturalLanguageUnderstandingErr := naturallanguageunderstandingv1.NewNaturalLanguageUnderstandingV1(options)\n\n// Check for errors\nif naturalLanguageUnderstandingErr != nil {\n panic(naturalLanguageUnderstandingErr)\n}\n\n// Call a method\nresult, _, responseErr := naturalLanguageUnderstanding.MethodName(&methodOptions)\n\n// Check for errors\nif responseErr != nil {\n panic(responseErr)\n}\n```\n\nThe Swift SDK returns a `WatsonError` in the `completionHandler` any unsuccessful method invocation. This error type is an enum that conforms to `LocalizedError` and contains an `errorDescription` property that returns an error message. Some of the `WatsonError` cases contain associated values that reveal more information about the error.\n\n| Field | Description |\n|----------------------|-------------------------------------|\n| **errorDescription** | A message that describes the error. |\n\nExample error handling\n\n```swift\nnaturalLanguageUnderstanding.method() {\n response, error in\n\n if let error = error {\n switch error {\n case let .http(statusCode, message, metadata):\n switch statusCode {\n case .some(404):\n // Handle Not Found (404) exception\n print(\"Not found\")\n case .some(413):\n // Handle Request Too Large (413) exception\n print(\"Payload too large\")\n default:\n if let statusCode = statusCode {\n print(\"Error - code: \\(statusCode), \\(message ?? \"\")\")\n }\n }\n default:\n print(error.localizedDescription)\n }\n return\n }\n\n guard let result = response?.result else {\n print(error?.localizedDescription ?? \"unknown error\")\n return\n }\n\n print(result)\n}\n```\n\nWhen the .NET Standard SDK receives an error response from the Natural Language Understanding service, it generates a `ServiceResponseException` with the following fields.\n\n| Field | Description |\n|---------------------|------------------------------------------|\n| **Message** | A message that describes the error. |\n| **CodeDescription** | The HTTP response code that is returned. |\n\nExample error handling\n\n```cs\ntry\n{\n // Invoke a method\n}\ncatch(ServiceResponseException e)\n{\n Console.WriteLine(\"Error: \" + e.Message);\n}\ncatch (Exception e)\n{\n Console.WriteLine(\"Error: \" + e.Message);\n}\n```\n\nWhen the Unity SDK receives an error response from the Natural Language Understanding service, it generates an `IBMError` with the following fields.\n\n| Field | Description |\n|---------------------|------------------------------------------------|\n| **Url** | The URL that generated the error. |\n| **StatusCode** | The HTTP response code returned. |\n| **ErrorMessage** | A message that describes the error. |\n| **Response** | The contents of the response from the server. |\n| **ResponseHeaders** | A dictionary of headers returned by the request. |\n\nExample error handling\n\n```cs\n// Invoke a method\nnaturalLanguageUnderstanding.MethodName(Callback, Parameters);\n\n// Check for errors\nprivate void Callback(DetailedResponse response, IBMError error)\n{\n if (error == null)\n {\n Log.Debug(\"ExampleCallback\", \"Response received: {0}\", response.Response);\n }\n else\n {\n Log.Debug(\"ExampleCallback\", \"Error received: {0}, {1}, {3}\", error.StatusCode, error.ErrorMessage, error.Response);\n }\n}\n```\n\n## Data handling\n\n### Additional headers\n\nSome Watson services accept special parameters in headers that are passed with the request.\n\nYou can pass request header parameters in all requests or in a single request to the service.\n\nTo pass a request header, use the `--header` (`-H`) option with a curl request.\n\nExample header parameter in a request\n\n```sh\ncurl -X {request_method} \\\n-H \"Request-Header: {header_value}\" \\\n\"{url}/v1/{method}\"\n```\n\nTo pass header parameters with every request, use the `setDefaultHeaders` method of the service object. See [Data collection](#data-collection) for an example use of this method.\n\nTo pass header parameters in a single request, use the `addHeader` method as a modifier on the request before you execute it.\n\nExample header parameter in a request\n\n```java\nReturnType returnValue = naturalLanguageUnderstanding.methodName(parameters)\n .addHeader(\"Custom-Header\", \"{header_value}\")\n .execute();\n```\n\nTo pass header parameters with every request, specify the `headers` parameter when you create the service object. See [Data collection](#data-collection) for an example use of this method.\n\nTo pass header parameters in a single request, use the `headers` method as a modifier on the request before you execute it.\n\nExample header parameter in a request\n\n```javascript\nconst parameters = {\n {parameters}\n};\n\nnaturalLanguageUnderstanding.methodName(\n parameters,\n headers: {\n 'Custom-Header': '{header_value}'\n })\n .then(result => {\n console.log(response);\n })\n .catch(err => {\n console.log('error:', err);\n });\n```\n\nTo pass header parameters with every request, specify the `set_default_headers` method of the service object. See [Data collection](#data-collection) for an example use of this method.\n\nTo pass header parameters in a single request, include `headers` as a `dict` in the request.\n\nExample header parameter in a request\n\n```python\nresponse = natural_language_understanding.methodName(\n parameters,\n headers = {\n 'Custom-Header': '{header_value}'\n })\n```\n\nTo pass header parameters with every request, specify the `add_default_headers` method of the service object. See [Data collection](#data-collection) for an example use of this method.\n\nTo pass header parameters in a single request, specify the `headers` method as a chainable method in the request.\n\nExample header parameter in a request\n\n```ruby\nresponse = natural_language_understanding.headers(\n \"Custom-Header\" => \"{header_value}\"\n).methodName(parameters)\n```\n\nTo pass header parameters with every request, specify the `SetDefaultHeaders` method of the service object. See [Data collection](#data-collection) for an example use of this method.\n\nTo pass header parameters in a single request, specify the `Headers` as a `map` in the request.\n\nExample header parameter in a request\n\n```go\nresult, _, responseErr := naturalLanguageUnderstanding.MethodName(\n &methodOptions{\n Headers: map[string]string{\n \"Accept\": \"application/json\",\n },\n },\n)\n```\n\nTo pass header parameters with every request, add them to the `defaultHeaders` property of the service object. See [Data collection](#data-collection) for an example use of this method.\n\nTo pass header parameters in a single request, pass the `headers` parameter to the request method.\n\nExample header parameter in a request\n\n```swift\nlet customHeader: [String: String] = [\"Custom-Header\": \"{header_value}\"]\nnaturalLanguageUnderstanding.methodName(parameters, headers: customHeader) {\n response, error in\n}\n```\n\nTo pass header parameters in a single request, use the `WithHeader()` method as a modifier on the request before you execute it. See [Data collection](#data-collection) for an example use of this method.\n\nExample header parameter in a request\n\n```cs\nIamAuthenticator authenticator = new IamAuthenticator(\n apikey: \"{apikey}\"\n );\n\nNaturalLanguageUnderstandingService naturalLanguageUnderstanding = new NaturalLanguageUnderstandingService(\"{version}\", authenticator);\nnaturalLanguageUnderstanding.SetServiceUrl(\"{url}\");\n\nnaturalLanguageUnderstanding.WithHeader(\"Custom-Header\", \"header_value\");\n```\n\nTo pass header parameters in a single request, use the `WithHeader()` method as a modifier on the request before you execute it.\n\nExample header parameter in a request\n\n```cs\nvar authenticator = new IamAuthenticator(\n apikey: \"{apikey}\"\n);\n\nwhile (!authenticator.CanAuthenticate())\n yield return null;\n\nvar naturalLanguageUnderstanding = new NaturalLanguageUnderstandingService(\"{version}\", authenticator);\nnaturalLanguageUnderstanding.SetServiceUrl(\"{url}\");\n\nnaturalLanguageUnderstanding.WithHeader(\"Custom-Header\", \"header_value\");\n```\n\n### Response details\n\nThe Natural Language Understanding service might return information to the application in response headers.\n\nTo access all response headers that the service returns, include the `--include` (`-i`) option with a curl request. To see detailed response data for the request, including request headers, response headers, and extra debugging information, include the `--verbose` (`-v`) option with the request.\n\nExample request to access response headers\n\n```sh\ncurl -X {request_method} {authentication_method} \\\n--include \\\n\"{url}/v1/{method}\"\n```\n\nTo access information in the response headers, use one of the request methods that returns details with the response: `executeWithDetails()`, `enqueueWithDetails()`, or `rxWithDetails()`. These methods return a `Response` object, where `T` is the expected response model. Use the `getResult()` method to access the response object for the method, and use the `getHeaders()` method to access information in response headers.\n\nExample request to access response headers\n\n```java\nResponse response = naturalLanguageUnderstanding.methodName(parameters)\n .executeWithDetails();\n// Access response from methodName\nReturnType returnValue = response.getResult();\n// Access information in response headers\nHeaders responseHeaders = response.getHeaders();\n```\n\nAll response data is available in the `Response` object that is returned by each method. To access information in the `response` object, use the following properties.\n\nExample request to access response headers\n\n```javascript\nnaturalLanguageUnderstanding.methodName(parameters)\n .then(response => {\n console.log(response.headers);\n })\n .catch(err => {\n console.log('error:', err);\n });\n```\n\n| Property | Description |\n|-----------|-------------------------------------------------------|\n| `result` | Returns the response for the service-specific method. |\n| `headers` | Returns the response header information. |\n| `status` | Returns the HTTP status code. |\n\nThe return value from all service methods is a `DetailedResponse` object. To access information in the result object or response headers, use the following methods.\n\nExample request to access response headers\n\n```python\nnatural_language_understanding.set_detailed_response(True)\nresponse = natural_language_understanding.methodName(parameters)\n## Access response from methodName\nprint(json.dumps(response.get_result(), indent=2))\n## Access information in response headers\nprint(response.get_headers())\n## Access HTTP response status\nprint(response.get_status_code())\n```\n\n**DetailedResponse**\n\n| Method | Description |\n|---------------------|-------------------------------------------------------|\n| `get_result()` | Returns the response for the service-specific method. |\n| `get_headers()` | Returns the response header information. |\n| `get_status_code()` | Returns the HTTP status code. |\n\nThe return value from all service methods is a `DetailedResponse` object. To access information in the `response` object, use the following properties.\n\nExample request to access response headers\n\n```ruby\nresponse = natural_language_understanding.methodName(parameters)\n## Access response from methodName\nprint response.result\n## Access information in response headers\nprint response.headers\n## Access HTTP response status\nprint response.status\n```\n\n**DetailedResponse**\n\n| Property | Description |\n|-----------|-------------------------------------------------------|\n| `result` | Returns the response for the service-specific method. |\n| `headers` | Returns the response header information. |\n| `status` | Returns the HTTP status code. |\n\nThe return value from all service methods is a `DetailedResponse` object. To access information in the `response` object or response headers, use the following methods.\n\nExample request to access response headers\n\n```go\nimport (\n \"github.com/IBM/go-sdk-core/core\"\n \"github.com/watson-developer-cloud/go-sdk/naturallanguageunderstandingv1\"\n)\nresult, response, responseErr := naturalLanguageUnderstanding.MethodName(\n &methodOptions{})\n// Access result\ncore.PrettyPrint(response.GetResult(), \"Result \")\n\n// Access response headers\ncore.PrettyPrint(response.GetHeaders(), \"Headers \")\n\n// Access status code\ncore.PrettyPrint(response.GetStatusCode(), \"Status Code \")\n```\n\n**DetailedResponse**\n\n| Method | Description |\n|-------------------|-------------------------------------------------------|\n| `GetResult()` | Returns the response for the service-specific method. |\n| `GetHeaders()` | Returns the response header information. |\n| `GetStatusCode()` | Returns the HTTP status code. |\n\nAll response data is available in the `WatsonResponse` object that is returned in each method's `completionHandler`.\n\nExample request to access response headers\n\n```swift\nnaturalLanguageUnderstanding.methodName(parameters) {\n response, error in\n\n guard let result = response?.result else {\n print(error?.localizedDescription ?? \"unknown error\")\n return\n }\n print(result) // The data returned by the service\n print(response?.statusCode)\n print(response?.headers)\n}\n```\n\nThe response contains fields for response headers, response JSON, and the status code.\n\nExample request to access response headers\n\n```cs\nvar results = naturalLanguageUnderstanding.MethodName(parameters);\n\nvar result = results.Result; // The result object\nvar responseHeaders = results.Headers; // The response headers\nvar responseJson = results.Response; // The raw response JSON\nvar statusCode = results.StatusCode; // The response status code\n```\n\n**DetailedResponse**\n\n| Property | Description |\n|--------------|----------------------------------------------------------------|\n| `Result` | Returns the result for the service-specific method. |\n| `Response` | Returns the raw JSON response for the service-specific method. |\n| `Headers` | Returns the response header information. |\n| `StatusCode` | Returns the HTTP status code. |\n\nThe response contains fields for response headers, response JSON, and the status code.\n\nExample request to access response headers\n\n```cs\nprivate void Example()\n{\n naturalLanguageUnderstanding.MethodName(Callback, Parameters);\n}\n\nprivate void Callback(DetailedResponse response, IBMError error)\n{\n var result = response.Result; // The result object\n var responseHeaders = response.Headers; // The response headers\n var responseJson = reresponsesults.Response; // The raw response JSON\n var statusCode = response.StatusCode; // The response status code\n}\n```\n\n**DetailedResponse**\n\n| Property | Description |\n|--------------|----------------------------------------------------------------|\n| `Result` | Returns the result for the service-specific method. |\n| `Response` | Returns the raw JSON response for the service-specific method. |\n| `Headers` | Returns the response header information. |\n| `StatusCode` | Returns the HTTP status code. |\n\n### Data collection\n\nExample request\n\n```sh\ncurl -u \"apikey:{apikey}\" \\\n-H \"X-Watson-Learning-Opt-Out: true\" \\\n\"{url}/{method}\"\n```\n\nExample request\n\n```java\nMap headers = new HashMap();\nheaders.put(\"X-Watson-Learning-Opt-Out\", \"true\");\n\nnaturalLanguageUnderstanding.setDefaultHeaders(headers);\n```\n\nExample request\n\n```javascript\nconst NaturalLanguageUnderstandingV1 = require('ibm-watson/natural-language-understanding/v1');\nconst { IamAuthenticator } = require('ibm-watson/auth');\n\nconst naturalLanguageUnderstanding = new NaturalLanguageUnderstandingV1({\n version: '{version}',\n authenticator: new IamAuthenticator({\n apikey: '{apikey}',\n }),\n serviceUrl: '{url}',\n headers: {\n 'X-Watson-Learning-Opt-Out': 'true'\n }\n});\n```\n\nExample request\n\n```python\nnatural_language_understanding.set_default_headers({'x-watson-learning-opt-out': \"true\"})\n```\n\nExample request\n\n```ruby\nnatural_language_understanding.add_default_headers(headers: {\"x-watson-learning-opt-out\" => \"true\"})\n```\n\nExample request\n\n```go\nimport \"net/http\"\n\nheaders := http.Header{}\nheaders.Add(\"x-watson-learning-opt-out\", \"true\")\nnaturalLanguageUnderstanding.SetDefaultHeaders(headers)\n```\n\nExample request\n\n```swift\nnaturalLanguageUnderstanding.defaultHeaders[\"X-Watson-Learning-Opt-Out\"] = \"true\"\n```\n\nExample request\n\n```cs\nIamAuthenticator authenticator = new IamAuthenticator(\n apikey: \"{apikey}\"\n );\n\nNaturalLanguageUnderstandingService naturalLanguageUnderstanding = new NaturalLanguageUnderstandingService(\"{version}\", authenticator);\nnaturalLanguageUnderstanding.SetServiceUrl(\"{url}\");\n\nnaturalLanguageUnderstanding.WithHeader(\"X-Watson-Learning-Opt-Out\", \"true\");\n```\n\nExample request\n\n```cs\nvar authenticator = new IamAuthenticator(\n apikey: \"{apikey}\"\n);\n\nwhile (!authenticator.CanAuthenticate())\n yield return null;\n\nvar naturalLanguageUnderstanding = new NaturalLanguageUnderstandingService(\"{version}\", authenticator);\nnaturalLanguageUnderstanding.SetServiceUrl(\"{url}\");\n\nnaturalLanguageUnderstanding.WithHeader(\"X-Watson-Learning-Opt-Out\", \"true\");\n```\n\nBy default, Natural Language Understanding service instances that are not part of Premium plans collect data about API requests and their results. This data is collected only to improve the services for future users. The collected data is not shared or made public. Data is not collected for services that are part of Premium plans.\n\nTo prevent IBM usage of your data for an API request, set the **X-Watson-Learning-Opt-Out** header parameter to `true`. You can also disable request logging at the account level. For more information, see [Controlling request logging for Watson services](https://cloud.ibm.com/docs/watson?topic=watson-gs-logging-overview).\n\nYou must set the header on each request that you do not want IBM to access for general service improvements.\n\nYou can set the header by using the `setDefaultHeaders` method of the service object.\n\nYou can set the header by using the `headers` parameter when you create the service object.\n\nYou can set the header by using the `set_default_headers` method of the service object.\n\nYou can set the header by using the `add_default_headers` method of the service object.\n\nYou can set the header by using the `SetDefaultHeaders` method of the service object.\n\nYou can set the header by adding it to the `defaultHeaders` property of the service object.\n\nYou can set the header by using the `WithHeader()` method of the service object.\n\n## Synchronous and asynchronous requests\n\nThe Java SDK supports both synchronous (blocking) and asynchronous (non-blocking) execution of service methods. All service methods implement the [ServiceCall](https://ibm.github.io/java-sdk-core/docs/9.5.4/com/ibm/cloud/sdk/core/http/ServiceCall.html) interface.\n\n- To call a method **synchronously**, use the `execute` method of the `ServiceCall` interface. You can call the `execute` method directly from an instance of the service.\n- To call a method **asynchronously**, use the `enqueue` method of the `ServiceCall` interface to receive a callback when the response arrives. The [ServiceCallback](https://ibm.github.io/java-sdk-core/docs/9.5.4/com/ibm/cloud/sdk/core/http/ServiceCallback.html) interface of the method's argument provides `onResponse` and `onFailure` methods that you override to handle the callback.\n\nExample synchronous request\n\n```java\nReturnType returnValue = naturalLanguageUnderstanding.method(parameters).execute();\n```\nExample asynchronous request\n\n```java\nnaturalLanguageUnderstanding.method(parameters).enqueue(new ServiceCallback() {\n @Override public void onResponse(ReturnType response) {\n . . .\n }\n @Override public void onFailure(Exception e) {\n . . .\n }\n});\n```\n\nThe Ruby SDK supports both synchronous (blocking) and asynchronous (non-blocking) execution of service methods. All service methods implement the [Concurrent::Async](http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Async.html) module. When you use the synchronous or asynchronous methods, an **IVar** object is returned. You access the `DetailedResponse` object by calling `ivar_object.value`.\n\nFor more information about the **Ivar** object, see the [IVar](http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/IVar.html) class docs.\n\n- To call a method **synchronously**, either call the method directly or use the `.await` chainable method of the `Concurrent::Async` module.\n\n Calling a method directly (without `.await`) returns a `DetailedResponse` object.\n \n- To call a method **asynchronously**, use the `.async` chainable method of the `Concurrent::Async` module.\n\nYou can call the `.await` and `.async` methods directly from an instance of the service.\n\nExample synchronous request\n\n```ruby\nresponse = natural_language_understanding.method_name(parameters)\n```\n\nor\n\n```ruby\nresponse = natural_language_understanding.await.method_name(parameters)\n```\n\nExample asynchronous request\n\n```ruby\nresponse = natural_language_understanding.async.method_name(parameters)\n```\n\n## Related information\n\n- Natural Language Understanding [docs](https://cloud.ibm.com/docs/natural-language-understanding)\n- [Release notes](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-release-notes)\n- [Javadoc for NaturalLanguageUnderstanding](http://watson-developer-cloud.github.io/java-sdk/docs/v12.0.1/com/ibm/watson/natural_language_understanding/v1/NaturalLanguageUnderstanding.html) \n- [Javadoc for sdk-core](https://ibm.github.io/java-sdk-core/docs/9.12.1/) \n\n[assistant-v1]: /apidocs/assistant-v1/\n[assistant-v1-java]: /apidocs/assistant-v1?code=java\n[assistant-v1-node]: /apidocs/assistant-v1?code=node\n[assistant-v1-python]: /apidocs/assistant-v1?code=python\n[assistant-v1-ruby]: /apidocs/assistant-v1?code=ruby\n[assistant-v1-go]: /apidocs/assistant-v1?code=go\n[assistant-v1-swift]: /apidocs/assistant-v1?code=swift\n[assistant-v1-dotnet-standard]: /apidocs/assistant-v1?code=dotnet-standard\n[assistant-v1-unity]: /apidocs/assistant-v1?code=unity\n[installed-assistant-v1]: /apidocs/assistant-data-v1\n[installed-assistant-v1-java]: /apidocs/assistant-data-v1?code=java\n[installed-assistant-v1-node]: /apidocs/assistant-data-v1?code=node\n[installed-assistant-v1-python]: /apidocs/assistant-data-v1?code=python\n[installed-assistant-v1-ruby]: /apidocs/assistant-data-v1?code=ruby\n[installed-assistant-v1-go]: /apidocs/assistant-data-v1?code=go\n[installed-assistant-v1-swift]: /apidocs/assistant-data-v1?code=swift\n[installed-assistant-v1-dotnet-standard]: /apidocs/assistant-data-v1?code=dotnet-standard\n[installed-assistant-v1-unity]: /apidocs/assistant-data-v1?code=unity\n\n[assistant-v2]: /apidocs/assistant-v2/\n[assistant-v2-java]: /apidocs/assistant-v2?code=java\n[assistant-v2-node]: /apidocs/assistant-v2?code=node\n[assistant-v2-python]: /apidocs/assistant-v2?code=python\n[assistant-v2-ruby]: /apidocs/assistant-v2?code=ruby\n[assistant-v2-go]: /apidocs/assistant-v2?code=go\n[assistant-v2-swift]: /apidocs/assistant-v2?code=swift\n[assistant-v2-dotnet-standard]: /apidocs/assistant-v2?code=dotnet-standard\n[assistant-v2-unity]: /apidocs/assistant-v2?code=unity\n[installed-assistant-v2]: /apidocs/assistant-data-v2\n[installed-assistant-v2-java]: /apidocs/assistant-data-v2?code=java\n[installed-assistant-v2-node]: /apidocs/assistant-data-v2?code=node\n[installed-assistant-v2-python]: /apidocs/assistant-data-v2?code=python\n[installed-assistant-v2-ruby]: /apidocs/assistant-data-v2?code=ruby\n[installed-assistant-v2-go]: /apidocs/assistant-data-v2?code=go\n[installed-assistant-v2-swift]: /apidocs/assistant-data-v2?code=swift\n[installed-assistant-v2-dotnet-standard]: /apidocs/assistant-data-v2?code=dotnet-standard\n[installed-assistant-v2-unity]: /apidocs/assistant-data-v2?code=unity\n\n[disco-v1]: /apidocs/discovery/\n[disco-v1-java]: /apidocs/discovery?code=java\n[disco-v1-node]: /apidocs/discovery?code=node\n[disco-v1-python]: /apidocs/discovery?code=python\n[disco-v1-ruby]: /apidocs/discovery?code=ruby\n[disco-v1-go]: /apidocs/discovery?code=go\n[disco-v1-swift]: /apidocs/discovery?code=swift\n[disco-v1-dotnet-standard]: /apidocs/discovery?code=dotnet-standard\n[disco-v1-unity]: /apidocs/discovery?code=unity\n[disco-v2]: /apidocs/discovery-data/\n[disco-v2-java]: /apidocs/discovery-data?code=java\n[disco-v2-node]: /apidocs/discovery-data?code=node\n[disco-v2-python]: /apidocs/discovery-data?code=python\n[disco-v2-ruby]: /apidocs/discovery-data?code=ruby\n[disco-v2-go]: /apidocs/discovery-data?code=go\n[disco-v2-swift]: /apidocs/discovery-data?code=swift\n[disco-v2-dotnet-standard]: /apidocs/discovery-data?code=dotnet-standard\n[disco-v2-unity]: /apidocs/discovery-data?code=unity",
"x-vcap-service-name": "natural-language-understanding",
"x-version-date": "2022-04-07",
"x-sdk-supported-languages": [
"java",
"node",
"python",
"dotnet-standard"
],
"x-codegen-config": {
"includeExternalConfig": true,
"supportNodeCallbacks": true,
"dotnet-standard": {
"apiPackage": "IBM.Watson"
},
"go": {
"apiPackage": "github.com/watson-developer-cloud/go-sdk/v2"
},
"cli": {
"apiPackage": "cli-watson-plugin",
"cliPluginName": "watson"
},
"java": {
"apiPackage": "com.ibm.watson"
},
"python": {
"apiPackage": "ibm_watson"
},
"swift": {
"resterror-alias": "WatsonError",
"restresponse-alias": "WatsonResponse"
}
},
"x-github": "https://github.ibm.com/cloud-api-docs/natural-language-understanding",
"x-github-issues": "https://github.ibm.com/cloud-api-docs/natural-language-understanding/issues/new",
"x-last-updated": "2024-05-10"
},
"security": [
{
"IAM": []
}
],
"externalDocs": {
"description": "For more information about this service, see the docs.",
"url": "https://cloud.ibm.com/docs/natural-language-understanding",
"x-information-security": "https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-information-security",
"x-release-notes": "https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-release-notes"
},
"x-doc-properties": [
"hasCustomEndpoints",
"publicDefinition"
],
"tags": [
{
"name": "Analyze"
},
{
"name": "Manage models"
},
{
"name": "Manage sentiment models"
},
{
"name": "Manage categories models"
},
{
"name": "Manage classifications models"
}
],
"paths": {
"/v1/analyze": {
"parameters": [
{
"$ref": "#/components/parameters/version"
}
],
"get": {
"operationId": "analyzeGet",
"summary": "Analyze text (GET)",
"description": "Analyzes raw text, HTML, or a public webpage.\n\nIf a language for the input text is not specified with the `language` parameter, the service [automatically detects the language](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-detectable-languages).",
"x-ibm-change-notices": [
{
"version": "2022-04-07",
"type": "breaking",
"description": "The advanced rules feature is removed. As of 24 June 2021, you can no longer run advanced rules models for Natural Language Understanding.",
"url": "https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-release-notes#5-may-2021"
}
],
"parameters": [
{
"$ref": "#/components/parameters/text"
},
{
"$ref": "#/components/parameters/html"
},
{
"$ref": "#/components/parameters/url"
},
{
"$ref": "#/components/parameters/features"
},
{
"$ref": "#/components/parameters/return_analyzed_text"
},
{
"$ref": "#/components/parameters/clean"
},
{
"$ref": "#/components/parameters/xpath"
},
{
"$ref": "#/components/parameters/fallback_to_raw"
},
{
"$ref": "#/components/parameters/language"
},
{
"$ref": "#/components/parameters/categories.explanation"
},
{
"$ref": "#/components/parameters/categories.limit"
},
{
"$ref": "#/components/parameters/categories.model"
},
{
"$ref": "#/components/parameters/classifications.model"
},
{
"$ref": "#/components/parameters/concepts.limit"
},
{
"$ref": "#/components/parameters/emotion.document"
},
{
"$ref": "#/components/parameters/emotion.targets"
},
{
"$ref": "#/components/parameters/entities.limit"
},
{
"$ref": "#/components/parameters/entities.mentions"
},
{
"$ref": "#/components/parameters/entities.model"
},
{
"$ref": "#/components/parameters/entities.emotion"
},
{
"$ref": "#/components/parameters/entities.sentiment"
},
{
"$ref": "#/components/parameters/keywords.limit"
},
{
"$ref": "#/components/parameters/keywords.emotion"
},
{
"$ref": "#/components/parameters/keywords.sentiment"
},
{
"$ref": "#/components/parameters/relations.model"
},
{
"$ref": "#/components/parameters/semantic_roles.limit"
},
{
"$ref": "#/components/parameters/semantic_roles.entities"
},
{
"$ref": "#/components/parameters/semantic_roles.keywords"
},
{
"$ref": "#/components/parameters/sentiment.document"
},
{
"$ref": "#/components/parameters/sentiment.targets"
},
{
"$ref": "#/components/parameters/syntax.tokens"
},
{
"$ref": "#/components/parameters/syntax.tokens.lemma"
},
{
"$ref": "#/components/parameters/syntax.tokens.part_of_speech"
},
{
"$ref": "#/components/parameters/syntax.sentences"
},
{
"$ref": "#/components/parameters/limit_text_characters"
}
],
"tags": [
"Analyze"
],
"responses": {
"200": {
"$ref": "#/components/responses/AnalyzeGetResponse"
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"x-sdk-operations": {
"request-examples": {
"curl": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"curl -u \"apikey:{apikey}\" \\\n",
" \"{url}/v1/analyze}?version=2022-04-07&url=www.ibm.com&features=keywords,entities&entities.emotion=true&entities.sentiment=true&keywords.emotion=true&keywords.sentiment=true\""
]
}
]
}
]
}
},
"x-sdk-exclude": true
},
"post": {
"operationId": "analyze",
"tags": [
"Analyze"
],
"summary": "Analyze text",
"description": "Analyzes text, HTML, or a public webpage for the following features:\n- Categories\n- Classifications\n- Concepts\n- Emotion\n- Entities\n- Keywords\n- Metadata\n- Relations\n- Semantic roles\n- Sentiment\n- Syntax\n- Summarization (Experimental)\n\nIf a language for the input text is not specified with the `language` parameter, the service [automatically detects the language](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-detectable-languages).",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Parameters"
}
}
},
"description": "An object containing request parameters. The `features` object and one of the `text`, `html`, or `url` attributes are required.",
"required": true
},
"x-codegen-request-body-name": "parameters",
"responses": {
"200": {
"$ref": "#/components/responses/AnalyzeResponse"
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"x-sdk-operations": {
"request-examples": {
"curl": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"curl -X POST -u \"apikey:{apikey}\" -H \"Content-Type: application/json\" -d @parameters.json \"{url}/v1/analyze?version=2022-04-07\""
]
}
]
},
{
"name": "Example parameters",
"example": [
{
"type": "code",
"source": [
"{\n",
" \"text\": \"IBM is an American multinational technology company headquartered in Armonk, New York, United States, with operations in over 170 countries.\",\n",
" \"features\": {\n",
" \"entities\": {\n",
" \"emotion\": true,\n",
" \"sentiment\": true,\n",
" \"limit\": 2\n",
" },\n",
" \"keywords\": {\n",
" \"emotion\": true,\n",
" \"sentiment\": true,\n",
" \"limit\": 2\n",
" }\n",
" }\n",
"}"
]
}
]
}
],
"dotnet-standard": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\n",
" apikey: \"{apikey}\"\n",
" );\n",
"\n",
"NaturalLanguageUnderstandingService naturalLanguageUnderstanding = new NaturalLanguageUnderstandingService(\"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.SetServiceUrl(\"{url}\");\n",
"\n",
"var features = new Features()\n",
"{\n",
" Keywords = new KeywordsOptions()\n",
" {\n",
" Limit = 2,\n",
" Sentiment = true,\n",
" Emotion = true\n",
" },\n",
" Entities = new EntitiesOptions()\n",
" {\n",
" Sentiment = true,\n",
" Limit = 2\n",
" }\n",
"};\n",
"\n",
"var result = naturalLanguageUnderstanding.Analyze(\n",
" features: features,\n",
" text: \"IBM is an American multinational technology company headquartered in Armonk, New York, United States, with operations in over 170 countries.\"\n",
" );\n",
"\n",
"Console.WriteLine(result.Response);"
]
}
]
}
],
"java": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\"{apikey}\");\n",
"NaturalLanguageUnderstanding naturalLanguageUnderstanding = new NaturalLanguageUnderstanding(\n",
" \"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.setServiceUrl(\"{url}\");\n",
"\n",
"String text = \"IBM is an American multinational technology \" +\n",
" \"company headquartered in Armonk, New York, \" +\n",
" \"United States, with operations in over 170 countries.\";\n",
"\n",
"EntitiesOptions entitiesOptions = new EntitiesOptions.Builder()\n",
" .emotion(true)\n",
" .sentiment(true)\n",
" .limit(2)\n",
" .build();\n",
"\n",
"KeywordsOptions keywordsOptions = new KeywordsOptions.Builder()\n",
" .emotion(true)\n",
" .sentiment(true)\n",
" .limit(2)\n",
" .build();\n",
"\n",
"Features features = new Features.Builder()\n",
" .entities(entitiesOptions)\n",
" .keywords(keywordsOptions)\n",
" .build();\n",
"\n",
"AnalyzeOptions parameters = new AnalyzeOptions.Builder()\n",
" .text(text)\n",
" .features(features)\n",
" .build();\n",
"\n",
"AnalysisResults response = naturalLanguageUnderstanding\n",
" .analyze(parameters)\n",
" .execute()\n",
" .getResult();\n",
"System.out.println(response);"
]
}
]
}
],
"node": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"const NaturalLanguageUnderstandingV1 = require('ibm-watson/natural-language-understanding/v1');\n",
"const { IamAuthenticator } = require('ibm-watson/auth');\n",
"\n",
"const naturalLanguageUnderstanding = new NaturalLanguageUnderstandingV1({\n",
" version: '2022-04-07',\n",
" authenticator: new IamAuthenticator({\n",
" apikey: '{apikey}',\n",
" }),\n",
" serviceUrl: '{url}',\n",
"});\n",
"\n",
"const analyzeParams = {\n",
" 'url': 'www.ibm.com',\n",
" 'features': {\n",
" 'entities': {\n",
" 'emotion': true,\n",
" 'sentiment': true,\n",
" 'limit': 2,\n",
" },\n",
" 'keywords': {\n",
" 'emotion': true,\n",
" 'sentiment': true,\n",
" 'limit': 2,\n",
" },\n",
" },\n",
"};\n",
"\n",
"naturalLanguageUnderstanding.analyze(analyzeParams)\n",
" .then(analysisResults => {\n",
" console.log(JSON.stringify(analysisResults, null, 2));\n",
" })\n",
" .catch(err => {\n",
" console.log('error:', err);\n",
" });"
]
}
]
}
],
"python": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"import json\n",
"from ibm_watson import NaturalLanguageUnderstandingV1\n",
"from ibm_cloud_sdk_core.authenticators import IAMAuthenticator\n",
"from ibm_watson.natural_language_understanding_v1 \\ \n",
" import Features, EntitiesOptions, KeywordsOptions\n",
"\n",
"authenticator = IAMAuthenticator('{apikey}')\n",
"natural_language_understanding = NaturalLanguageUnderstandingV1(\n",
" version='2022-04-07',\n",
" authenticator=authenticator)\n",
"\n",
"natural_language_understanding.set_service_url('{url}')\n",
"\n",
"response = natural_language_understanding.analyze(\n",
" text='IBM is an American multinational technology company '\n",
" 'headquartered in Armonk, New York, United States, '\n",
" 'with operations in over 170 countries.',\n",
" features=Features(\n",
" entities=EntitiesOptions(emotion=True, sentiment=True, limit=2),\n",
" keywords=KeywordsOptions(emotion=True, sentiment=True,\n",
" limit=2))).get_result()\n",
"\n",
"print(json.dumps(response, indent=2))"
]
}
]
}
]
}
}
}
},
"/v1/models": {
"get": {
"operationId": "listModels",
"tags": [
"Manage models"
],
"summary": "List models",
"description": "Lists Watson Knowledge Studio [custom entities and relations models](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-customizing) that are deployed to your Natural Language Understanding service.",
"parameters": [
{
"$ref": "#/components/parameters/version"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/ListModelsResponse"
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"x-sdk-operations": {
"request-examples": {
"curl": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"curl -u \"apikey:{apikey}\" \"{url}/v1/models?version=2022-04-07\""
]
}
]
}
],
"dotnet-standard": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\n",
" apikey: \"{apikey}\"\n",
" );\n",
"\n",
"NaturalLanguageUnderstandingService naturalLanguageUnderstanding = new NaturalLanguageUnderstandingService(\"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.SetServiceUrl(\"{url}\");\n",
"\n",
"var result = naturalLanguageUnderstanding.ListModels();\n",
"\n",
"Console.WriteLine(result.Response);"
]
}
]
}
],
"java": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\"{apikey}\");\n",
"NaturalLanguageUnderstanding naturalLanguageUnderstanding = new NaturalLanguageUnderstanding(\n",
" \"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.setServiceUrl(\"{url}\");\n",
"\n",
"ListModelsResults models = naturalLanguageUnderstanding\n",
" .listModels()\n",
" .execute()\n",
" .getResult();\n",
"System.out.println(models);"
]
}
]
}
],
"node": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"const NaturalLanguageUnderstandingV1 = require('ibm-watson/natural-language-understanding/v1');\n",
"const { IamAuthenticator } = require('ibm-watson/auth');\n",
"\n",
"const naturalLanguageUnderstanding = new NaturalLanguageUnderstandingV1({\n",
" version: '2022-04-07',\n",
" authenticator: new IamAuthenticator({\n",
" apikey: '{apikey}',\n",
" }),\n",
" serviceUrl: '{url}',\n",
"});\n",
"\n",
"naturalLanguageUnderstanding.listModels()\n",
" .then(listModelsResults => {\n",
" console.log(JSON.stringify(listModelsResults, null, 2));\n",
" })\n",
" .catch(err => {\n",
" console.log('error:', err);\n",
" });"
]
}
]
}
],
"python": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"import json\n",
"from ibm_watson import NaturalLanguageUnderstandingV1\n",
"from ibm_cloud_sdk_core.authenticators import IAMAuthenticator\n",
"\n",
"authenticator = IAMAuthenticator('{apikey}')\n",
"natural_language_understanding = NaturalLanguageUnderstandingV1(\n",
" version='2022-04-07',\n",
" authenticator=authenticator)\n",
"\n",
"natural_language_understanding.set_service_url('{url}')\n",
"\n",
"response = natural_language_understanding.list_models().get_result()\n",
"\n",
"print(json.dumps(response, indent=2))"
]
}
]
}
]
}
}
}
},
"/v1/models/{model_id}": {
"delete": {
"operationId": "deleteModel",
"tags": [
"Manage models"
],
"summary": "Delete model",
"description": "Deletes a custom model",
"parameters": [
{
"$ref": "#/components/parameters/version"
},
{
"name": "model_id",
"description": "Model ID of the model to delete",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DeleteModelResponse"
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"x-sdk-operations": {
"request-examples": {
"curl": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"curl -X DELETE -u \"apikey:{apikey}\" \"{url}/v1/models/{model_id}?version=2022-04-07\""
]
}
]
}
],
"dotnet-standard": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\n",
" apikey: \"{apikey}\"\n",
" );\n",
"\n",
"NaturalLanguageUnderstandingService naturalLanguageUnderstanding = new NaturalLanguageUnderstandingService(\"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.SetServiceUrl(\"{url}\");\n",
"\n",
"var result = naturalLanguageUnderstanding.DeleteModel(\n",
" modelId: \"model_id\"\n",
" );\n",
"\n",
"Console.WriteLine(result.Response);"
]
}
]
}
],
"java": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\"{apikey}\");\n",
"NaturalLanguageUnderstanding naturalLanguageUnderstanding = new NaturalLanguageUnderstanding(\n",
" \"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.setServiceUrl(\"{url}\");\n",
"\n",
"DeleteModelOptions options = new DeleteModelOptions.Builder().modelId(\"model_id\").build();\n",
"naturalLanguageUnderstanding.deleteModel(options).execute();"
]
}
]
}
],
"node": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"const NaturalLanguageUnderstandingV1 = require('ibm-watson/natural-language-understanding/v1');\n",
"const { IamAuthenticator } = require('ibm-watson/auth');\n",
"\n",
"const naturalLanguageUnderstanding = new NaturalLanguageUnderstandingV1({\n",
" version: '2022-04-07',\n",
" authenticator: new IamAuthenticator({\n",
" apikey: '{apikey}',\n",
" }),\n",
" serviceUrl: '{url}',\n",
"});\n",
"\n",
"const deleteModelParams = {\n",
" 'modelId': '{model-id}',\n",
"};\n",
"\n",
"naturalLanguageUnderstanding.deleteModel(deleteModelParams)\n",
" .then(deleteModelResults => {\n",
" console.log(JSON.stringify(deleteModelResults, null, 2));\n",
" })\n",
" .catch(err => {\n",
" console.log('error:', err);\n",
" });"
]
}
]
}
],
"python": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"import json\n",
"from ibm_watson import NaturalLanguageUnderstandingV1\n",
"from ibm_cloud_sdk_core.authenticators import IAMAuthenticator\n",
"\n",
"authenticator = IAMAuthenticator('{apikey}')\n",
"natural_language_understanding = NaturalLanguageUnderstandingV1(\n",
" version='2022-04-07',\n",
" authenticator=authenticator)\n",
"\n",
"natural_language_understanding.set_service_url('{url}')\n",
"\n",
"response = natural_language_understanding.delete_model(\n",
" model_id='model_id').get_result()\n",
"\n",
"print(json.dumps(response, indent=2))"
]
}
]
}
]
}
}
}
},
"/v1/models/categories": {
"parameters": [
{
"$ref": "#/components/parameters/version"
}
],
"post": {
"tags": [
"Manage categories models"
],
"summary": "Create categories model",
"description": "(Beta) Creates a custom categories model by uploading training data and associated metadata. The model begins the training and deploying process and is ready to use when the `status` is `available`.",
"operationId": "createCategoriesModel",
"responses": {
"201": {
"description": "Model created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CategoriesModel"
},
"examples": {
"response": {
"value": {
"name": "MyCategoriesModel",
"language": "en",
"model_version": "1.0.1",
"status": "training",
"notices": [],
"model_id": "cb3755ad-d226-4587-b956-43a4a7202202",
"features": [
"categories"
],
"created": "2020-04-10T19:32:42Z",
"last_trained": "2020-04-10T19:32:42Z",
"last_deployed": "2020-04-10T19:32:42Z"
}
}
}
}
},
"links": {
"getCategoriesModel": {
"operationId": "getCategoriesModel",
"parameters": {
"model_id": "$response.body#/model_id"
}
},
"updateCategoriesModel": {
"operationId": "updateCategoriesModel",
"parameters": {
"model_id": "$response.body#/model_id"
}
},
"deleteCategoriesModel": {
"operationId": "deleteCategoriesModel",
"parameters": {
"model_id": "$response.body#/model_id"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Access forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/CategoriesModelFileAndMetadata"
}
}
}
},
"x-sdk-operations": {
"request-examples": {
"curl": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"curl -X POST -u \"apikey:{apikey}\" \\\n",
"-H \"Content-Type: multipart/form-data\" \\\n",
"-F \"training_data=@categories_data.json;type=application/json\" \\\n",
"-F \"language=en\" \\\n",
"-F \"name=MyCategoriesModel\" \\\n",
"-F \"model_version=1.0.1\" \\\n",
"\"{url}/v1/models/categories?version=2022-04-07\""
]
}
]
}
],
"dotnet-standard": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\n",
" apikey: \"{apikey}\"\n",
" );\n",
"\n",
"NaturalLanguageUnderstandingService naturalLanguageUnderstanding = new NaturalLanguageUnderstandingService(\"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.SetServiceUrl(\"{url}\");\n",
"\n",
"var result = naturalLanguageUnderstanding.CreateCategoriesModel(\n",
" language: \"en\",\n",
" trainingData: new MemoryStream(File.ReadAllBytes(\"trainingData.json\")),\n",
" trainingDataContentType: NaturalLanguageUnderstandingService.CreateCategoriesModelEnums.TrainingDataContentTypeValue.APPLICATION_JSON,\n",
" name: \"MyCategoriesModel\",\n",
" modelVersion: \"1.0.1\"\n",
" );\n",
"\n",
"Console.WriteLine(result.Response);"
]
}
]
}
],
"java": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\"{apikey}\");\n",
"NaturalLanguageUnderstanding naturalLanguageUnderstanding = new NaturalLanguageUnderstanding(\n",
" \"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.setServiceUrl(\"{url}\");\n",
"\n",
"try {\n",
" CreateCategoriesModelOptions createCategoriesModelOptions = new CreateCategoriesModelOptions.Builder()\n",
" .language(\"en\")\n",
" .trainingData(new FileInputStream(\"trainingData.json\"))\n",
" .trainingDataContentType(\"application/json\")\n",
" .name(\"testString\")\n",
" .description(\"testString\")\n",
" .modelVersion(\"testString\")\n",
" .versionDescription(\"testString\")\n",
" .build();\n",
"\n",
" CategoriesModel response = naturalLanguageUnderstanding.createCategoriesModel(createCategoriesModelOptions).execute().getResult();\n",
"\n",
" System.out.println(response);\n",
"} catch (FileNotFoundException e) {\n",
" e.printStackTrace();\n",
"}"
]
}
]
}
],
"node": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"const fs = require('fs');\n",
"const NaturalLanguageUnderstandingV1 = require('ibm-watson/natural-language-understanding/v1');\n",
"const { IamAuthenticator } = require('ibm-watson/auth');\n",
"\n",
"const naturalLanguageUnderstanding = new NaturalLanguageUnderstandingV1({\n",
" version: '2022-04-07',\n",
" authenticator: new IamAuthenticator({\n",
" apikey: '{apikey}',\n",
" }),\n",
" serviceUrl: '{url}',\n",
"});\n",
"\n",
"const createCategoriesModelParams = {\n",
" language: 'en',\n",
" trainingData: fs.createReadStream('./categories_data.json'),\n",
" name: 'MyCategoriesModel',\n",
" modelVersion: '1.0.1'\n",
"};\n",
"\n",
"naturalLanguageUnderstanding.createCategoriesModel(createCategoriesModelParams)\n",
" .then(createCategoriesModelResults => {\n",
" console.log(JSON.stringify(createCategoriesModelResults, null, 2));\n",
" })\n",
" .catch(err => {\n",
" console.log('error:', err);\n",
" });"
]
}
]
}
],
"python": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"from os.path import join, dirname\n",
"from ibm_watson import NaturalLanguageUnderstandingV1\n",
"from ibm_cloud_sdk_core.authenticators import IAMAuthenticator\n",
"\n",
"authenticator = IAMAuthenticator('{apikey}')\n",
"natural_language_understanding = NaturalLanguageUnderstandingV1(\n",
" version='2022-04-07',\n",
" authenticator=authenticator\n",
")\n",
"\n",
"natural_language_understanding.set_service_url('{url}')\n",
"\n",
"with open(join(dirname(__file__), './.', 'categories_data.json'),\n",
" 'rb') as file:\n",
" model=natural_language_understanding.create_categories_model(\n",
" language='en',\n",
" training_data=file\n",
" name='MyCategoriesModel',\n",
" model_version='1.0.1',\n",
" ).get_result()\n",
" print(json.dumps(model, indent=2))"
]
}
]
}
]
}
}
},
"get": {
"tags": [
"Manage categories models"
],
"summary": "List categories models",
"description": "(Beta) Returns all custom categories models associated with this service instance.",
"operationId": "listCategoriesModels",
"responses": {
"200": {
"description": "Models retrieved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CategoriesModelList"
},
"examples": {
"response": {
"value": {
"models": [
{
"name": "MyCategoriesModel",
"language": "en",
"model_version": "1.0.1",
"status": "available",
"notices": [],
"model_id": "cb3755ad-d226-4587-b956-43a4a7202202",
"features": [
"categories"
],
"created": "2020-04-10T19:32:42Z",
"last_trained": "2020-04-10T19:32:42Z",
"last_deployed": "2020-04-10T19:32:42Z"
}
]
}
}
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Access forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"x-sdk-operations": {
"request-examples": {
"curl": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"curl -u \"apikey:{apikey}\" \\\n",
"\"{url}/v1/models/categories?version=2022-04-07\""
]
}
]
}
],
"dotnet-standard": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\n",
" apikey: \"{apikey}\"\n",
" );\n",
"\n",
"NaturalLanguageUnderstandingService naturalLanguageUnderstanding = new NaturalLanguageUnderstandingService(\"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.SetServiceUrl(\"{url}\");\n",
"\n",
"var result = naturalLanguageUnderstanding.ListCategoriesModels();\n",
"\n",
"Console.WriteLine(result.Response);"
]
}
]
}
],
"java": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\"{apikey}\");\n",
"NaturalLanguageUnderstanding naturalLanguageUnderstanding = new NaturalLanguageUnderstanding(\n",
" \"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.setServiceUrl(\"{url}\");\n",
"\n",
"CategoriesModelList response = naturalLanguageUnderstanding.listCategoriesModels().execute().getResult();\n",
"\n",
"System.out.println(response);"
]
}
]
}
],
"node": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"const NaturalLanguageUnderstandingV1 = require('ibm-watson/natural-language-understanding/v1');\n",
"const { IamAuthenticator } = require('ibm-watson/auth');\n",
"\n",
"const naturalLanguageUnderstanding = new NaturalLanguageUnderstandingV1({\n",
" version: '2022-04-07',\n",
" authenticator: new IamAuthenticator({\n",
" apikey: '{apikey}',\n",
" }),\n",
" serviceUrl: '{url}',\n",
"});\n",
"\n",
"naturalLanguageUnderstanding.listCategoriesModels()\n",
" .then(listCategoriesModelsResults => {\n",
" console.log(JSON.stringify(listCategoriesModelsResults, null, 2));\n",
" })\n",
" .catch(err => {\n",
" console.log('error:', err);\n",
" });"
]
}
]
}
],
"python": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"import json\n",
"from ibm_watson import NaturalLanguageUnderstandingV1\n",
"from ibm_cloud_sdk_core.authenticators import IAMAuthenticator\n",
"\n",
"authenticator = IAMAuthenticator('{apikey}')\n",
"natural_language_understanding = NaturalLanguageUnderstandingV1(\n",
" version='2022-04-07',\n",
" authenticator=authenticator)\n",
"\n",
"natural_language_understanding.set_service_url('{url}')\n",
"\n",
"models = natural_language_understanding.list_categories_models().get_result()\n",
"\n",
"print(json.dumps(models, indent=2))"
]
}
]
}
]
}
}
}
},
"/v1/models/categories/{model_id}": {
"parameters": [
{
"$ref": "#/components/parameters/version"
},
{
"$ref": "#/components/parameters/model_id"
}
],
"get": {
"tags": [
"Manage categories models"
],
"summary": "Get categories model details",
"description": "(Beta) Returns the status of the categories model with the given model ID.",
"operationId": "getCategoriesModel",
"responses": {
"200": {
"description": "Model retrieved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CategoriesModel"
},
"examples": {
"response": {
"value": {
"name": "MyCategoriesModel",
"language": "en",
"model_version": "1.0.1",
"status": "available",
"notices": [],
"model_id": "cb3755ad-d226-4587-b956-43a4a7202202",
"features": [
"categories"
],
"created": "2020-04-10T19:32:42Z",
"last_trained": "2020-04-10T19:32:42Z",
"last_deployed": "2020-04-10T19:32:42Z"
}
}
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Access forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"x-sdk-operations": {
"request-examples": {
"curl": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"curl -u \"apikey:{apikey}\" \\\n",
"\"{url}/v1/models/categories/{model_id}?version=2022-04-07\""
]
}
]
}
],
"dotnet-standard": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\n",
" apikey: \"{apikey}\"\n",
" );\n",
"\n",
"NaturalLanguageUnderstandingService naturalLanguageUnderstanding = new NaturalLanguageUnderstandingService(\"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.SetServiceUrl(\"{url}\");\n",
"\n",
"var result = naturalLanguageUnderstanding.GetCategoriesModel(\n",
" modelId: \"{modelId}\"\n",
" );\n",
"\n",
"Console.WriteLine(result.Response);"
]
}
]
}
],
"java": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\"{apikey}\");\n",
"NaturalLanguageUnderstanding naturalLanguageUnderstanding = new NaturalLanguageUnderstanding(\n",
" \"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.setServiceUrl(\"{url}\");\n",
"\n",
"GetCategoriesModelOptions getCategoriesModelOptions = new GetCategoriesModelOptions.Builder()\n",
" .modelId(\"{modelId}\")\n",
" .build();\n",
"\n",
"CategoriesModel response = naturalLanguageUnderstanding.getCategoriesModel(getCategoriesModelOptions).execute().getResult();\n",
"\n",
"System.out.println(response);"
]
}
]
}
],
"node": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"const NaturalLanguageUnderstandingV1 = require('ibm-watson/natural-language-understanding/v1');\n",
"const { IamAuthenticator } = require('ibm-watson/auth');\n",
"\n",
"const naturalLanguageUnderstanding = new NaturalLanguageUnderstandingV1({\n",
" version: '2022-04-07',\n",
" authenticator: new IamAuthenticator({\n",
" apikey: '{apikey}',\n",
" }),\n",
" serviceUrl: '{url}',\n",
"});\n",
"\n",
"const getCategoriesModelParams = {\n",
" modelId: '{model_id}',\n",
"};\n",
"\n",
"naturalLanguageUnderstanding.getCategoriesModel(getCategoriesModelParams)\n",
" .then(getCategoriesModelResults => {\n",
" console.log(JSON.stringify(getCategoriesModelResults, null, 2));\n",
" })\n",
" .catch(err => {\n",
" console.log('error:', err);\n",
" });"
]
}
]
}
],
"python": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"import json\n",
"from ibm_watson import NaturalLanguageUnderstandingV1\n",
"from ibm_cloud_sdk_core.authenticators import IAMAuthenticator\n",
"\n",
"authenticator = IAMAuthenticator('{apikey}')\n",
"natural_language_understanding = NaturalLanguageUnderstandingV1(\n",
" version='2022-04-07',\n",
" authenticator=authenticator)\n",
"\n",
"natural_language_understanding.set_service_url('{url}')\n",
"\n",
"model = natural_language_understanding.get_categories_model(\n",
" model_id='{model_id}',\n",
").get_result()\n",
"\n",
"\n",
"print(json.dumps(model, indent=2))"
]
}
]
}
]
}
}
},
"put": {
"tags": [
"Manage categories models"
],
"summary": "Update categories model",
"description": "(Beta) Overwrites the training data associated with this custom categories model and retrains the model. The new model replaces the current deployment.",
"operationId": "updateCategoriesModel",
"responses": {
"200": {
"description": "Model overwrite successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CategoriesModel"
},
"examples": {
"response": {
"value": {
"models": [
{
"name": "MyCategoriesModel",
"language": "en",
"model_version": "1.0.1",
"status": "deploying",
"notices": [],
"model_id": "cb3755ad-d226-4587-b956-43a4a7202202",
"features": [
"categories"
],
"created": "2020-04-10T20:21:46Z",
"last_trained": "2020-04-10T20:21:46Z",
"last_deployed": "2020-04-10T20:21:46Z"
}
]
}
}
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Access forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/CategoriesModelFileAndMetadata"
}
}
}
},
"x-sdk-operations": {
"request-examples": {
"curl": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"curl -X PUT -u \"apikey:{apikey}\" \\\n",
"-H \"Content-Type: multipart/form-data\" \\\n",
"-F \"training_data=@categories_model.json;type=application/json\" \\\n",
"-F \"language=en\" \\\n",
"-F \"name=MyCategoriesModel\" \\\n",
"-F \"description=My updated categories model\" \\\n",
"-F \"model_version=1.0.1\" \\\n",
"-F \"version_description=Updated version\" \\\n",
"\"{url}/v1/models/categories/{model_id}?version=2022-04-07\""
]
}
]
}
],
"dotnet-standard": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\n",
" apikey: \"{apikey}\"\n",
" );\n",
"\n",
"NaturalLanguageUnderstandingService naturalLanguageUnderstanding = new NaturalLanguageUnderstandingService(\"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.SetServiceUrl(\"{url}\");\n",
"\n",
"var result = naturalLanguageUnderstanding.UpdateCategoriesModel(\n",
" modelId: \"{modelId}\",\n",
" trainingData: new MemoryStream(File.ReadAllBytes(\"trainingData.json\")),\n",
" language: \"en\",\n",
" name: \"MyCategoriesModel\",\n",
" description: \"My updated categories model\",\n",
" modelVersion: \"1.0.1\",\n",
" versionDescription: \"Updated version\"\n",
" );\n",
"\n",
"Console.WriteLine(result.Response);"
]
}
]
}
],
"java": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\"{apikey}\");\n",
"NaturalLanguageUnderstanding naturalLanguageUnderstanding = new NaturalLanguageUnderstanding(\n",
" \"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.setServiceUrl(\"{url}\");\n",
"\n",
"try {\n",
" UpdateCategoriesModelOptions updateCategoriesModelOptions = new UpdateCategoriesModelOptions.Builder()\n",
" .language(\"en\")\n",
" .trainingData(new FileInputStream(\"trainingData.json\"))\n",
" .trainingDataContentType(\"application/json\")\n",
" .name(\"newName\")\n",
" .description(\"newDescription\")\n",
" .modelVersion(\"testString\")\n",
" .versionDescription(\"testString\")\n",
" .modelId(\"{modelId}\")\n",
" .build();\n",
"\n",
" CategoriesModel response = naturalLanguageUnderstanding.updateCategoriesModel(updateCategoriesModelOptions).execute().getResult();\n",
"\n",
" System.out.println(response);\n",
"} catch (FileNotFoundException e) {\n",
" e.printStackTrace();\n",
"}"
]
}
]
}
],
"node": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"const fs = require('fs');\n",
"const NaturalLanguageUnderstandingV1 = require('ibm-watson/natural-language-understanding/v1');\n",
"const { IamAuthenticator } = require('ibm-watson/auth');\n",
"\n",
"const naturalLanguageUnderstanding = new NaturalLanguageUnderstandingV1({\n",
" version: '2022-04-07',\n",
" authenticator: new IamAuthenticator({\n",
" apikey: '{apikey}',\n",
" }),\n",
" serviceUrl: '{url}',\n",
"});\n",
"\n",
"const updateCategoriesModelParams = {\n",
" language: 'en',\n",
" trainingData: fs.createReadStream('./categories_model.json'),\n",
" name: 'MyCategoriesModel',\n",
" description: 'My updated categories model',\n",
" modelVersion: '1.0.1',\n",
" versionDescription: 'Updated version',\n",
" modelId: '{model_id}'\n",
"};\n",
"\n",
"naturalLanguageUnderstanding.updateCategoriesModel(updateCategoriesModelParams)\n",
" .then(updateCategoriesModelResults => {\n",
" console.log(JSON.stringify(updateCategoriesModelResults, null, 2));\n",
" })\n",
" .catch(err => {\n",
" console.log('error:', err);\n",
" });"
]
}
]
}
],
"python": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"from os.path import join, dirname\n",
"from ibm_watson import NaturalLanguageUnderstandingV1\n",
"from ibm_cloud_sdk_core.authenticators import IAMAuthenticator\n",
"\n",
"authenticator = IAMAuthenticator('{apikey}')\n",
"natural_language_understanding = NaturalLanguageUnderstandingV1(\n",
" version='2022-04-07',\n",
" authenticator=authenticator\n",
")\n",
"\n",
"natural_language_understanding.set_service_url('{url}')\n",
"\n",
"with open(join(dirname(__file__), './.', 'categories_model.json'),\n",
" 'rb') as file:\n",
" model=natural_language_understanding.update_categories_model(\n",
" language='en',\n",
" training_data=file\n",
" name='MyCategoriesModel',\n",
" description='My updated categories model',\n",
" model_version='1.0.1',\n",
" version_description='Updated version',\n",
" model_id='{model_id}'\n",
" ).get_result()\n",
" print(json.dumps(model, indent=2))"
]
}
]
}
]
}
}
},
"delete": {
"tags": [
"Manage categories models"
],
"summary": "Delete categories model",
"description": "(Beta) Un-deploys the custom categories model with the given model ID and deletes all associated customer data, including any training data or binary artifacts.",
"operationId": "deleteCategoriesModel",
"responses": {
"200": {
"$ref": "#/components/responses/DeleteModelResponse"
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Access forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"x-sdk-operations": {
"request-examples": {
"curl": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"curl -X DELETE -u \"apikey:{apikey}\" \\\n",
"\"{url}/v1/models/categories/{model_id}?version=2022-04-07\""
]
}
]
}
],
"dotnet-standard": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\n",
" apikey: \"{apikey}\"\n",
" );\n",
"\n",
"NaturalLanguageUnderstandingService naturalLanguageUnderstanding = new NaturalLanguageUnderstandingService(\"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.SetServiceUrl(\"{url}\");\n",
"\n",
"var result = naturalLanguageUnderstanding.DeleteCategoriesModel(\n",
" modelId: \"{modelId}\"\n",
" );\n",
"\n",
"Console.WriteLine(result.Response);"
]
}
]
}
],
"java": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\"{apikey}\");\n",
"NaturalLanguageUnderstanding naturalLanguageUnderstanding = new NaturalLanguageUnderstanding(\n",
" \"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.setServiceUrl(\"{url}\");\n",
"\n",
"DeleteCategoriesModelOptions deleteCategoriesModelOptions = new DeleteCategoriesModelOptions.Builder()\n",
" .modelId(\"{modelId}\")\n",
" .build();\n",
"\n",
"DeleteModelResults response = naturalLanguageUnderstanding.deleteCategoriesModel(deleteCategoriesModelOptions).execute().getResult();\n",
" \n",
"System.out.println(response);"
]
}
]
}
],
"node": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"const NaturalLanguageUnderstandingV1 = require('ibm-watson/natural-language-understanding/v1');\n",
"const { IamAuthenticator } = require('ibm-watson/auth');\n",
"\n",
"const naturalLanguageUnderstanding = new NaturalLanguageUnderstandingV1({\n",
" version: '2022-04-07',\n",
" authenticator: new IamAuthenticator({\n",
" apikey: '{apikey}',\n",
" }),\n",
" serviceUrl: '{url}',\n",
"});\n",
"\n",
"const deleteCategoriesModelParams = {\n",
" modelId: '{model_id}',\n",
"};\n",
"\n",
"naturalLanguageUnderstanding.deleteCategoriesModel(deleteCategoriesModelParams)\n",
" .then(deleteCategoriesModelResults => {\n",
" console.log(JSON.stringify(deleteCategoriesModelResults, null, 2));\n",
" })\n",
" .catch(err => {\n",
" console.log('error:', err);\n",
" });"
]
}
]
}
],
"python": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"import json\n",
"from ibm_watson import NaturalLanguageUnderstandingV1\n",
"from ibm_cloud_sdk_core.authenticators import IAMAuthenticator\n",
"\n",
"authenticator = IAMAuthenticator('{apikey}')\n",
"natural_language_understanding = NaturalLanguageUnderstandingV1(\n",
" version='2022-04-07',\n",
" authenticator=authenticator)\n",
"\n",
"natural_language_understanding.set_service_url('{url}')\n",
"\n",
"model = natural_language_understanding.delete_categories_model(\n",
" model_id='{model_id}',\n",
").get_result()\n",
"\n",
"\n",
"print(json.dumps(model, indent=2))"
]
}
]
}
]
}
}
}
},
"/v1/models/classifications": {
"parameters": [
{
"$ref": "#/components/parameters/version"
}
],
"post": {
"tags": [
"Manage classifications models"
],
"summary": "Create classifications model",
"description": "Creates a custom classifications model by uploading training data and associated metadata. The model begins the training and deploying process and is ready to use when the `status` is `available`.",
"operationId": "createClassificationsModel",
"responses": {
"201": {
"description": "Model created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClassificationsModel"
},
"examples": {
"response": {
"value": {
"name": "MyClassificationsModel",
"language": "en",
"model_version": "1.0.1",
"status": "training",
"notices": [],
"model_id": "cb3755ad-d226-4587-b956-43a4a7202202",
"features": [
"classifications"
],
"created": "2020-04-10T19:32:42Z",
"last_trained": "2020-04-10T19:32:42Z",
"last_deployed": "2020-04-10T19:32:42Z"
}
}
}
}
},
"links": {
"getClassificationsModel": {
"operationId": "getClassificationsModel",
"parameters": {
"model_id": "$response.body#/model_id"
}
},
"updateClassificationsModel": {
"operationId": "updateClassificationsModel",
"parameters": {
"model_id": "$response.body#/model_id"
}
},
"deleteClassificationsModel": {
"operationId": "deleteClassificationsModel",
"parameters": {
"model_id": "$response.body#/model_id"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Access forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/ClassificationsModelFileMetadataAndTrainingParameters"
}
}
}
},
"x-sdk-operations": {
"request-examples": {
"curl": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"curl -X POST -u \"apikey:{apikey}\" \\\n",
"-H \"Content-Type: multipart/form-data\" \\\n",
"-F \"training_data=@classifications_data.json;type=application/json\" \\\n",
"-F \"language=en\" \\\n",
"-F \"name=MyClassificationsModel\" \\\n",
"-F \"model_version=1.0.1\" \\\n",
"\"{url}/v1/models/classifications?version=2022-04-07\""
]
}
]
}
],
"dotnet-standard": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\n",
" apikey: \"{apikey}\"\n",
" );\n",
"\n",
"NaturalLanguageUnderstandingService naturalLanguageUnderstanding = new NaturalLanguageUnderstandingService(\"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.SetServiceUrl(\"{url}\");\n",
"\n",
"var result = naturalLanguageUnderstanding.CreateClassificationsModel(\n",
" trainingData: new MemoryStream(File.ReadAllBytes(\"trainingData.json\")),\n",
" trainingDataContentType: NaturalLanguageUnderstandingService.CreateClassificationsModelEnums.TrainingDataContentTypeValue.APPLICATION_JSON,\n",
" language: \"en\",\n",
" name: \"MyClassificationsModel\",\n",
" modelVersion: \"1.0.1\"\n",
" );\n",
"\n",
"Console.WriteLine(result.Response);"
]
}
]
}
],
"java": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\"{apikey}\");\n",
"NaturalLanguageUnderstanding naturalLanguageUnderstanding = new NaturalLanguageUnderstanding(\n",
" \"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.setServiceUrl(\"{url}\");\n",
"\n",
"try {\n",
" CreateClassificationsModelOptions createClassificationsModelOptions = new CreateClassificationsModelOptions.Builder()\n",
" .language(\"en\")\n",
" .trainingData(new FileInputStream(\"trainingData.json\"))\n",
" .trainingDataContentType(\"application/json\")\n",
" .name(\"testString\")\n",
" .description(\"testString\")\n",
" .modelVersion(\"testString\")\n",
" .versionDescription(\"testString\")\n",
" .build();\n",
"\n",
" ClassificationsModel response = naturalLanguageUnderstanding.createClassificationsModel(createClassificationsModelOptions).execute().getResult();\n",
"\n",
" System.out.println(response);\n",
"} catch (FileNotFoundException e) {\n",
" e.printStackTrace();\n",
"}"
]
}
]
}
],
"node": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"const fs = require('fs');\n",
"const NaturalLanguageUnderstandingV1 = require('ibm-watson/natural-language-understanding/v1');\n",
"const { IamAuthenticator } = require('ibm-watson/auth');\n",
"\n",
"const naturalLanguageUnderstanding = new NaturalLanguageUnderstandingV1({\n",
" version: '2022-04-07',\n",
" authenticator: new IamAuthenticator({\n",
" apikey: '{apikey}',\n",
" }),\n",
" serviceUrl: '{url}',\n",
"});\n",
"\n",
"const createClassificationsModelParams = {\n",
" language: 'en',\n",
" trainingData: fs.createReadStream('./classifications_data.json'),\n",
" name: 'MyClassificationsModel',\n",
" modelVersion: '1.0.1',\n",
"};\n",
"\n",
"naturalLanguageUnderstanding.createClassificationsModel(createClassificationsModelParams)\n",
" .then(createClassificationsModelResults => {\n",
" console.log(JSON.stringify(createClassificationsModelResults, null, 2));\n",
" })\n",
" .catch(err => {\n",
" console.log('error:', err);\n",
" });"
]
}
]
}
],
"python": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"from os.path import join, dirname\n",
"from ibm_watson import NaturalLanguageUnderstandingV1\n",
"from ibm_cloud_sdk_core.authenticators import IAMAuthenticator\n",
"\n",
"authenticator = IAMAuthenticator('{apikey}')\n",
"natural_language_understanding = NaturalLanguageUnderstandingV1(\n",
" version='2022-04-07',\n",
" authenticator=authenticator\n",
")\n",
"\n",
"natural_language_understanding.set_service_url('{url}')\n",
"\n",
"with open(join(dirname(__file__), './.', 'classifications_data.json'),\n",
" 'rb') as file:\n",
" model=natural_language_understanding.create_classifications_model(\n",
" language='en',\n",
" training_data=file\n",
" name='MyClassificationsModel',\n",
" model_version='1.0.1',\n",
" ).get_result()\n",
" print(json.dumps(model, indent=2))"
]
}
]
}
]
}
}
},
"get": {
"tags": [
"Manage classifications models"
],
"summary": "List classifications models",
"description": "Returns all custom classifications models associated with this service instance.",
"operationId": "listClassificationsModels",
"responses": {
"200": {
"description": "Models retrieved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClassificationsModelList"
},
"examples": {
"response": {
"value": {
"models": [
{
"name": "MyClassificationsModel",
"language": "en",
"model_version": "1.0.1",
"status": "available",
"notices": [],
"model_id": "cb3755ad-d226-4587-b956-43a4a7202202",
"features": [
"classifications"
],
"created": "2020-04-10T19:32:42Z",
"last_trained": "2020-04-10T19:32:42Z",
"last_deployed": "2020-04-10T19:32:42Z"
}
]
}
}
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Access forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"x-sdk-operations": {
"request-examples": {
"curl": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"curl -u \"apikey:{apikey}\" \\\n",
"\"{url}/v1/models/classifications?version=2022-04-07\""
]
}
]
}
],
"dotnet-standard": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\n",
" apikey: \"{apikey}\"\n",
" );\n",
"\n",
"NaturalLanguageUnderstandingService naturalLanguageUnderstanding = new NaturalLanguageUnderstandingService(\"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.SetServiceUrl(\"{url}\");\n",
"\n",
"var result = naturalLanguageUnderstanding.ListClassificationsModels();\n",
"\n",
"Console.WriteLine(result.Response);"
]
}
]
}
],
"java": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\"{apikey}\");\n",
"NaturalLanguageUnderstanding naturalLanguageUnderstanding = new NaturalLanguageUnderstanding(\n",
" \"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.setServiceUrl(\"{url}\");\n",
"\n",
"ListClassificationsModelsResponse response = naturalLanguageUnderstanding.listClassificationsModels().execute().getResult();\n",
"\n",
"System.out.println(response);"
]
}
]
}
],
"node": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"const NaturalLanguageUnderstandingV1 = require('ibm-watson/natural-language-understanding/v1');\n",
"const { IamAuthenticator } = require('ibm-watson/auth');\n",
"\n",
"const naturalLanguageUnderstanding = new NaturalLanguageUnderstandingV1({\n",
" version: '2022-04-07',\n",
" authenticator: new IamAuthenticator({\n",
" apikey: '{apikey}',\n",
" }),\n",
" serviceUrl: '{url}',\n",
"});\n",
"\n",
"naturalLanguageUnderstanding.listClassificationsModels()\n",
" .then(listClassificationsModelsResults => {\n",
" console.log(JSON.stringify(listClassificationsModelsResults, null, 2));\n",
" })\n",
" .catch(err => {\n",
" console.log('error:', err);\n",
" });"
]
}
]
}
],
"python": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"import json\n",
"from ibm_watson import NaturalLanguageUnderstandingV1\n",
"from ibm_cloud_sdk_core.authenticators import IAMAuthenticator\n",
"\n",
"authenticator = IAMAuthenticator('{apikey}')\n",
"natural_language_understanding = NaturalLanguageUnderstandingV1(\n",
" version='2022-04-07',\n",
" authenticator=authenticator)\n",
"\n",
"natural_language_understanding.set_service_url('{url}')\n",
"\n",
"models = natural_language_understanding.list_classifications_models().get_result()\n",
"\n",
"print(json.dumps(models, indent=2))"
]
}
]
}
]
}
}
}
},
"/v1/models/classifications/{model_id}": {
"parameters": [
{
"$ref": "#/components/parameters/version"
},
{
"$ref": "#/components/parameters/model_id"
}
],
"get": {
"tags": [
"Manage classifications models"
],
"summary": "Get classifications model details",
"description": "Returns the status of the classifications model with the given model ID.",
"operationId": "getClassificationsModel",
"responses": {
"200": {
"description": "Model retrieved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClassificationsModel"
},
"examples": {
"response": {
"value": {
"name": "MyClassificationsModel",
"language": "en",
"model_version": "1.0.1",
"status": "available",
"notices": [],
"model_id": "cb3755ad-d226-4587-b956-43a4a7202202",
"features": [
"classifications"
],
"created": "2020-04-10T19:32:42Z",
"last_trained": "2020-04-10T19:32:42Z",
"last_deployed": "2020-04-10T19:32:42Z"
}
}
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Access forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"x-sdk-operations": {
"request-examples": {
"curl": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"curl -u \"apikey:{apikey}\" \\\n",
"\"{url}/v1/models/classifications/{model_id}?version=2022-04-07\""
]
}
]
}
],
"dotnet-standard": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\n",
" apikey: \"{apikey}\"\n",
" );\n",
"\n",
"NaturalLanguageUnderstandingService naturalLanguageUnderstanding = new NaturalLanguageUnderstandingService(\"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.SetServiceUrl(\"{url}\");\n",
"\n",
"var result = naturalLanguageUnderstanding.GetClassificationsModel(\n",
" modelId: \"{modelId}\"\n",
" );\n",
"\n",
"Console.WriteLine(result.Response);"
]
}
]
}
],
"java": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\"{apikey}\");\n",
"NaturalLanguageUnderstanding naturalLanguageUnderstanding = new NaturalLanguageUnderstanding(\n",
" \"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.setServiceUrl(\"{url}\");\n",
"\n",
"GetClassificationsModelOptions getClassificationsModelOptions = new GetClassificationsModelOptions.Builder()\n",
" .modelId(\"{modelId}\")\n",
" .build();\n",
"\n",
"ClassificationsModel response = naturalLanguageUnderstanding.getClassificationsModel(getClassificationsModelOptions).execute().getResult();\n",
"\n",
"System.out.println(response);"
]
}
]
}
],
"node": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"const NaturalLanguageUnderstandingV1 = require('ibm-watson/natural-language-understanding/v1');\n",
"const { IamAuthenticator } = require('ibm-watson/auth');\n",
"\n",
"const naturalLanguageUnderstanding = new NaturalLanguageUnderstandingV1({\n",
" version: '2022-04-07',\n",
" authenticator: new IamAuthenticator({\n",
" apikey: '{apikey}',\n",
" }),\n",
" serviceUrl: '{url}',\n",
"});\n",
"\n",
"const getClassificationsModelParams = {\n",
" modelId: '{model_id}',\n",
"};\n",
"\n",
"naturalLanguageUnderstanding.getClassificationsModel(getClassificationsModelParams)\n",
" .then(getClassificationsModelResults => {\n",
" console.log(JSON.stringify(getClassificationsModelResults, null, 2));\n",
" })\n",
" .catch(err => {\n",
" console.log('error:', err);\n",
" });"
]
}
]
}
],
"python": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"import json\n",
"from ibm_watson import NaturalLanguageUnderstandingV1\n",
"from ibm_cloud_sdk_core.authenticators import IAMAuthenticator\n",
"\n",
"authenticator = IAMAuthenticator('{apikey}')\n",
"natural_language_understanding = NaturalLanguageUnderstandingV1(\n",
" version='2022-04-07',\n",
" authenticator=authenticator)\n",
"\n",
"natural_language_understanding.set_service_url('{url}')\n",
"\n",
"model = natural_language_understanding.get_classifications_model(\n",
" model_id='{model_id}',\n",
").get_result()\n",
"\n",
"\n",
"print(json.dumps(model, indent=2))"
]
}
]
}
]
}
}
},
"put": {
"tags": [
"Manage classifications models"
],
"summary": "Update classifications model",
"description": "Overwrites the training data associated with this custom classifications model and retrains the model. The new model replaces the current deployment.",
"operationId": "updateClassificationsModel",
"responses": {
"200": {
"description": "Model overwrite successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClassificationsModel"
},
"examples": {
"response": {
"value": {
"models": [
{
"name": "MyClassificationsModel",
"language": "en",
"model_version": "1.0.1",
"status": "deploying",
"notices": [],
"model_id": "cb3755ad-d226-4587-b956-43a4a7202202",
"features": [
"classifications"
],
"created": "2020-04-10T20:21:46Z",
"last_trained": "2020-04-10T20:21:46Z",
"last_deployed": "2020-04-10T20:21:46Z"
}
]
}
}
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Access forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/ClassificationsModelFileMetadataAndTrainingParameters"
}
}
}
},
"x-sdk-operations": {
"request-examples": {
"curl": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"curl -X PUT -u \"apikey:{apikey}\" \\\n",
"-H \"Content-Type: multipart/form-data\" \\\n",
"-F \"training_data=@classifications_model.json;type=application/json\" \\\n",
"-F \"language=en\" \\\n",
"-F \"name=MyClassificationsModel\" \\\n",
"-F \"description=My updated classifications model\" \\\n",
"-F \"model_version=1.0.1\" \\\n",
"-F \"version_description=Updated version\" \\\n",
"\"{url}/v1/models/classifications/{model_id}?version=2022-04-07\""
]
}
]
}
],
"dotnet-standard": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\n",
" apikey: \"{apikey}\"\n",
" );\n",
"\n",
"NaturalLanguageUnderstandingService naturalLanguageUnderstanding = new NaturalLanguageUnderstandingService(\"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.SetServiceUrl(\"{url}\");\n",
"\n",
"var result = naturalLanguageUnderstanding.UpdateClassificationsModel(\n",
" modelId: \"{modelId}\",\n",
" trainingData: new MemoryStream(File.ReadAllBytes(\"trainingData.json\")),\n",
" language: \"en\",\n",
" name: \"MyClassificationsModel\",\n",
" description: \"My updated classifications model\",\n",
" modelVersion: \"1.0.1\",\n",
" versionDescription: \"Updated version\"\n",
" );\n",
"\n",
"Console.WriteLine(result.Response);"
]
}
]
}
],
"java": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\"{apikey}\");\n",
"NaturalLanguageUnderstanding naturalLanguageUnderstanding = new NaturalLanguageUnderstanding(\n",
" \"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.setServiceUrl(\"{url}\");\n",
"\n",
"try {\n",
" UpdateClassificationsModelOptions updateClassificationsModelOptions = new UpdateClassificationsModelOptions.Builder()\n",
" .language(\"en\")\n",
" .trainingData(new FileInputStream(\"trainingData.json\"))\n",
" .trainingDataContentType(\"application/json\")\n",
" .name(\"newName\")\n",
" .description(\"newDescription\")\n",
" .modelVersion(\"testString\")\n",
" .versionDescription(\"testString\")\n",
" .modelId(\"{modelId}\")\n",
" .build();\n",
" \n",
" ClassificationsModel response = naturalLanguageUnderstanding.updateClassificationsModel(updateClassificationsModelOptions).execute().getResult();\n",
" \n",
" System.out.println(response);\n",
"} catch (FileNotFoundException e) {\n",
" e.printStackTrace();\n",
"}"
]
}
]
}
],
"node": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"const fs = require('fs');\n",
"const NaturalLanguageUnderstandingV1 = require('ibm-watson/natural-language-understanding/v1');\n",
"const { IamAuthenticator } = require('ibm-watson/auth');\n",
"\n",
"const naturalLanguageUnderstanding = new NaturalLanguageUnderstandingV1({\n",
" version: '2022-04-07',\n",
" authenticator: new IamAuthenticator({\n",
" apikey: '{apikey}',\n",
" }),\n",
" serviceUrl: '{url}',\n",
"});\n",
"\n",
"const updateClassificationsModelParams = {\n",
" language: 'en',\n",
" trainingData: fs.createReadStream('./classifications_model.json'),\n",
" name: 'MyClassificationsModel',\n",
" description: 'My updated classifications model',\n",
" modelVersion: '1.0.1',\n",
" versionDescription: 'Updated version',\n",
" modelId: '{model_id}'\n",
"};\n",
"\n",
"naturalLanguageUnderstanding.updateClassificationsModel(updateClassificationsModelParams)\n",
" .then(updateClassificationsModelResults => {\n",
" console.log(JSON.stringify(updateClassificationsModelResults, null, 2));\n",
" })\n",
" .catch(err => {\n",
" console.log('error:', err);\n",
" });"
]
}
]
}
],
"python": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"from os.path import join, dirname\n",
"from ibm_watson import NaturalLanguageUnderstandingV1\n",
"from ibm_cloud_sdk_core.authenticators import IAMAuthenticator\n",
"\n",
"authenticator = IAMAuthenticator('{apikey}')\n",
"natural_language_understanding = NaturalLanguageUnderstandingV1(\n",
" version='2022-04-07',\n",
" authenticator=authenticator\n",
")\n",
"\n",
"natural_language_understanding.set_service_url('{url}')\n",
"\n",
"with open(join(dirname(__file__), './.', 'classifications_model.json'),\n",
" 'rb') as file:\n",
" model=natural_language_understanding.update_classifications_model(\n",
" language='en',\n",
" training_data=file\n",
" name='MyClassificationsModel',\n",
" description='My updated classifications model',\n",
" model_version='1.0.1',\n",
" version_description='Updated version',\n",
" model_id='{model_id}'\n",
" ).get_result()\n",
" print(json.dumps(model, indent=2))"
]
}
]
}
]
}
}
},
"delete": {
"tags": [
"Manage classifications models"
],
"summary": "Delete classifications model",
"description": "Un-deploys the custom classifications model with the given model ID and deletes all associated customer data, including any training data or binary artifacts.",
"operationId": "deleteClassificationsModel",
"responses": {
"200": {
"$ref": "#/components/responses/DeleteModelResponse"
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Access forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"x-sdk-operations": {
"request-examples": {
"curl": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"curl -X DELETE -u \"apikey:{apikey}\" \\\n",
"\"{url}/v1/models/classifications/{model_id}?version=2022-04-07\""
]
}
]
}
],
"dotnet-standard": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\n",
" apikey: \"{apikey}\"\n",
" );\n",
"\n",
"NaturalLanguageUnderstandingService naturalLanguageUnderstanding = new NaturalLanguageUnderstandingService(\"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.SetServiceUrl(\"{url}\");\n",
"\n",
"var result = naturalLanguageUnderstanding.DeleteClassificationsModel(\n",
" modelId: \"{modelId}\"\n",
" );\n",
"\n",
"Console.WriteLine(result.Response);"
]
}
]
}
],
"java": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"IamAuthenticator authenticator = new IamAuthenticator(\"{apikey}\");\n",
"NaturalLanguageUnderstanding naturalLanguageUnderstanding = new NaturalLanguageUnderstanding(\n",
" \"2022-04-07\", authenticator);\n",
"naturalLanguageUnderstanding.setServiceUrl(\"{url}\");\n",
"\n",
"DeleteClassificationsModelOptions deleteClassificationsModelOptions = new DeleteClassificationsModelOptions.Builder()\n",
" .modelId(\"{modelId}\")\n",
" .build();\n",
"\n",
"DeleteModelResults response = naturalLanguageUnderstanding.deleteClassificationsModel(deleteClassificationsModelOptions).execute().getResult();"
]
}
]
}
],
"node": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"const NaturalLanguageUnderstandingV1 = require('ibm-watson/natural-language-understanding/v1');\n",
"const { IamAuthenticator } = require('ibm-watson/auth');\n",
"\n",
"const naturalLanguageUnderstanding = new NaturalLanguageUnderstandingV1({\n",
" version: '2022-04-07',\n",
" authenticator: new IamAuthenticator({\n",
" apikey: '{apikey}',\n",
" }),\n",
" serviceUrl: '{url}',\n",
"});\n",
"\n",
"const deleteClassificationsModelParams = {\n",
" modelId: '{model_id}',\n",
"};\n",
"\n",
"naturalLanguageUnderstanding.deleteClassificationsModel(deleteClassificationsModelParams)\n",
" .then(deleteClassificationsModelResults => {\n",
" console.log(JSON.stringify(deleteClassificationsModelResults, null, 2));\n",
" })\n",
" .catch(err => {\n",
" console.log('error:', err);\n",
" });"
]
}
]
}
],
"python": [
{
"name": "Example request",
"example": [
{
"type": "code",
"source": [
"import json\n",
"from ibm_watson import NaturalLanguageUnderstandingV1\n",
"from ibm_cloud_sdk_core.authenticators import IAMAuthenticator\n",
"\n",
"authenticator = IAMAuthenticator('{apikey}')\n",
"natural_language_understanding = NaturalLanguageUnderstandingV1(\n",
" version='2022-04-07',\n",
" authenticator=authenticator)\n",
"\n",
"natural_language_understanding.set_service_url('{url}')\n",
"\n",
"model = natural_language_understanding.delete_classifications_model(\n",
" model_id='{model_id}',\n",
").get_result()\n",
"\n",
"\n",
"print(json.dumps(model, indent=2))"
]
}
]
}
]
}
}
}
}
},
"servers": [
{
"url": "https://api.us-south.natural-language-understanding.watson.cloud.ibm.com",
"description": "Dallas"
}
],
"components": {
"parameters": {
"version": {
"name": "version",
"in": "query",
"description": "Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is `2022-04-07`.",
"required": true,
"schema": {
"type": "string"
},
"x-sdk-global-param": true
},
"text": {
"name": "text",
"description": "URL-encoded text to analyze. One of the `text`, `html`, or `url` parameters is required.",
"in": "query",
"schema": {
"type": "string"
}
},
"html": {
"name": "html",
"description": "URL-encoded HTML to analyze. One of the `text`, `html`, or `url` parameters is required.",
"in": "query",
"schema": {
"type": "string"
}
},
"url": {
"name": "url",
"description": "Public webpage to analyze. One of the `text`, `html`, or `url` parameters is required. `url` is not supported in IBM Cloud Dedicated instances.",
"in": "query",
"schema": {
"type": "string"
}
},
"language": {
"name": "language",
"description": "ISO 639-1 code that specifies the language of your text. This overrides automatic language detection. Language support differs depending on the features you include in your analysis. For more information, see [Language support](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-language-support).",
"in": "query",
"schema": {
"type": "string"
}
},
"limit_text_characters": {
"name": "limit_text_characters",
"description": "Sets the maximum number of characters that are processed by the service.",
"in": "query",
"schema": {
"type": "integer"
}
},
"model_id": {
"name": "model_id",
"description": "ID of the model",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
"features": {
"name": "features",
"description": "Comma separated list of analysis features",
"in": "query",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"categories",
"classifications",
"concepts",
"emotion",
"entities",
"keywords",
"metadata",
"relations",
"semantic_roles",
"sentiment",
"summarization (experimental)",
"syntax"
]
}
}
},
"clean": {
"name": "clean",
"description": "Set this to `false` to disable text cleaning when analyzing webpages. For more information about webpage cleaning, see [Analyzing webpages](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-analyzing-webpages).",
"in": "query",
"schema": {
"type": "boolean",
"default": true
}
},
"xpath": {
"name": "xpath",
"description": "An [XPath query](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-analyzing-webpages#xpath) to perform on `html` or `url` input. Results of the query will be appended to the cleaned webpage text before it is analyzed. To analyze only the results of the XPath query, set the `clean` parameter to `false`.",
"in": "query",
"schema": {
"type": "string"
}
},
"fallback_to_raw": {
"name": "fallback_to_raw",
"description": "Whether to use raw HTML content if text cleaning fails",
"in": "query",
"schema": {
"type": "boolean",
"default": true
}
},
"return_analyzed_text": {
"name": "return_analyzed_text",
"description": "Set this to `true` to show the analyzed text in the response",
"in": "query",
"schema": {
"type": "boolean",
"default": false
}
},
"advanced_rules.model": {
"name": "advanced_rules.model",
"deprecated": true,
"description": "The advanced rules feature is deprecated. Existing models are supported until 24 June 2021, but after 10 June 2021, you will not be able to deploy advanced rules models to Natural Language Understanding. After 24 June 2021, advanced rules models will not run in Natural Language Understanding.\n\nAn advanced rules model ID",
"in": "query",
"schema": {
"type": "string"
}
},
"categories.explanation": {
"name": "categories.explanation",
"description": "Set this to `true` to return explanations for each categorization. **This feature is available only for English language text.**",
"in": "query",
"schema": {
"type": "boolean",
"default": false
}
},
"categories.limit": {
"name": "categories.limit",
"description": "Maximum number of categories to return.",
"in": "query",
"schema": {
"type": "integer",
"maximum": 10,
"default": 3
}
},
"categories.model": {
"name": "categories.model",
"description": "(Beta) Enter a [custom model](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-customizing) ID to override the standard categories model. **This feature is available only for English language text.**",
"in": "query",
"schema": {
"type": "string"
}
},
"classifications.model": {
"name": "classifications.model",
"description": "Model ID of the classifications model to be used",
"in": "query",
"schema": {
"type": "string"
}
},
"concepts.limit": {
"name": "concepts.limit",
"description": "Maximum number of concepts to return.",
"in": "query",
"schema": {
"type": "integer",
"maximum": 50,
"default": 8
}
},
"emotion.document": {
"name": "emotion.document",
"description": "Set this to `false` to hide document-level emotion results",
"in": "query",
"schema": {
"type": "boolean",
"default": true
}
},
"emotion.targets": {
"name": "emotion.targets",
"description": "Target strings, separated by commas. Emotion results will be returned for each target string found in the document",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
"entities.limit": {
"name": "entities.limit",
"description": "Maximum number of entities to return.",
"in": "query",
"schema": {
"type": "integer",
"maximum": 250,
"default": 50
}
},
"entities.mentions": {
"name": "entities.mentions",
"description": "Set this to `true` to return locations of entity mentions",
"in": "query",
"schema": {
"type": "boolean",
"default": false
}
},
"entities.model": {
"name": "entities.model",
"description": "Enter a [custom model](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-customizing) ID to override the standard entity detection model",
"in": "query",
"schema": {
"type": "string"
}
},
"entities.emotion": {
"name": "entities.emotion",
"description": "Set this to `true` to return emotion information for detected entities",
"in": "query",
"schema": {
"type": "boolean",
"default": false
}
},
"entities.sentiment": {
"name": "entities.sentiment",
"description": "Set this to `true` to return sentiment information for detected entities",
"in": "query",
"schema": {
"type": "boolean",
"default": false
}
},
"keywords.emotion": {
"name": "keywords.emotion",
"description": "Set this to `true` to return emotion information for detected keywords",
"in": "query",
"schema": {
"type": "boolean",
"default": false
}
},
"keywords.limit": {
"name": "keywords.limit",
"description": "Maximum number of keywords to return.",
"in": "query",
"schema": {
"type": "integer",
"maximum": 250,
"default": 50
}
},
"keywords.sentiment": {
"name": "keywords.sentiment",
"description": "Set this to `true` to return sentiment information for detected keywords",
"in": "query",
"schema": {
"type": "boolean",
"default": false
}
},
"relations.model": {
"name": "relations.model",
"description": "Enter a [custom model](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-customizing) ID to override the default `en-news` relations model",
"in": "query",
"schema": {
"type": "string",
"default": "en-news"
}
},
"semantic_roles.limit": {
"name": "semantic_roles.limit",
"description": "Maximum number of semantic_roles results to return",
"in": "query",
"schema": {
"type": "integer",
"default": 50
}
},
"semantic_roles.entities": {
"name": "semantic_roles.entities",
"description": "Set this to `true` to return entity information for subjects and objects",
"in": "query",
"schema": {
"type": "boolean",
"default": false
}
},
"semantic_roles.keywords": {
"name": "semantic_roles.keywords",
"description": "Set this to `true` to return keyword information for subjects and objects",
"in": "query",
"schema": {
"type": "boolean",
"default": false
}
},
"sentiment.document": {
"name": "sentiment.document",
"description": "Set this to `false` to disable document level sentiment analysis",
"in": "query",
"schema": {
"type": "boolean",
"default": true
}
},
"sentiment.targets": {
"name": "sentiment.targets",
"description": "Sentiment information will return for each target string that is found in the text",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
"sentiment.model": {
"name": "sentiment.model",
"description": "(Beta) Enter a [custom model](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-customizing) ID to override the standard sentiment model for all sentiment analysis operations in the request, including targeted sentiment for entities and keywords.",
"in": "query",
"schema": {
"type": "string"
},
"x-sdk-exclude": true
},
"syntax.tokens": {
"name": "syntax.tokens",
"description": "Set this to `true` to return information about the tokens in the input text.",
"in": "query",
"schema": {
"type": "boolean",
"default": false
}
},
"syntax.tokens.lemma": {
"name": "syntax.tokens.lemma",
"description": "Set this to `true` to return the lemma for each token.",
"in": "query",
"schema": {
"type": "boolean",
"default": false
}
},
"syntax.tokens.part_of_speech": {
"name": "syntax.tokens.part_of_speech",
"description": "Set this to `true` to return the part of speech for each token.",
"in": "query",
"schema": {
"type": "boolean",
"default": false
}
},
"syntax.sentences": {
"name": "syntax.sentences",
"description": "Set this to `true` to return information about the sentences in the input text.",
"in": "query",
"schema": {
"type": "boolean",
"default": false
}
}
},
"responses": {
"AnalyzeGetResponse": {
"description": "Analysis results",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AnalysisResults"
},
"examples": {
"response": {
"value": {
"entities": [
{
"type": "Company",
"relevance": 0.89792,
"count": 12,
"name": "IBM",
"disambiguation": {
"name": "IBM",
"dbpedia_resource": "http://dbpedia.org/resource/IBM",
"subtype": [
"SoftwareLicense",
"OperatingSystemDeveloper",
"ProcessorManufacturer",
"SoftwareDeveloper",
"CompanyFounder",
"ProgrammingLanguageDesigner",
"ProgrammingLanguageDeveloper"
]
},
"emotion": {
"sadness": 0.271362,
"joy": 0.618694,
"fear": 0.033186,
"disgust": 0.056113,
"anger": 0.099437
}
}
],
"keywords": [
{
"emotion": {
"sadness": 0.174379,
"joy": 0.66067,
"fear": 0.051475,
"disgust": 0.114401,
"anger": 0.044105
},
"relevance": "0.900808",
"sentiment": {
"score": 0.419889
},
"text": "free trial",
"count": 1
}
],
"language": "en",
"retrieved_url": "https://www.ibm.com/us-en/"
}
}
}
}
}
},
"AnalyzeResponse": {
"description": "Analysis results",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AnalysisResults"
},
"examples": {
"response": {
"value": {
"entities": [
{
"type": "Company",
"relevance": 0.89792,
"count": 12,
"name": "IBM",
"disambiguation": {
"name": "IBM",
"dbpedia_resource": "http://dbpedia.org/resource/IBM",
"subtype": [
"SoftwareLicense",
"OperatingSystemDeveloper",
"ProcessorManufacturer",
"SoftwareDeveloper",
"CompanyFounder",
"ProgrammingLanguageDesigner",
"ProgrammingLanguageDeveloper"
]
},
"emotion": {
"sadness": 0.271362,
"joy": 0.618694,
"fear": 0.033186,
"disgust": 0.056113,
"anger": 0.099437
}
}
],
"keywords": [
{
"emotion": {
"sadness": 0.174379,
"joy": 0.66067,
"fear": 0.051475,
"disgust": 0.114401,
"anger": 0.044105
},
"relevance": "0.900808",
"sentiment": {
"score": 0.419889
},
"text": "free trial",
"count": 1
}
],
"language": "en",
"retrieved_url": "https://www.ibm.com/us-en/"
}
}
}
}
}
},
"ListModelsResponse": {
"description": "List models results",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListModelsResults"
},
"examples": {
"response": {
"value": {
"models": [
{
"workspace_id": "504503a0-62c1-12e9-8346-d190294d088d",
"version_description": "Initial version",
"model_version": "1.0.1",
"version": "1.0.1",
"status": "available",
"notices": [],
"name": "MyAdvancedRulesModel",
"model_id": "2987ca3f-205f-4786-a168-2d8026ddcc9b",
"language": "en",
"description": "My custom advanced rules model",
"created": "2019-04-24T14:50:22Z"
}
]
}
}
}
}
}
},
"DeleteModelResponse": {
"description": "Delete model results",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteModelResults"
},
"examples": {
"response": {
"value": {
"deleted": "2987ca3f-205f-4786-a168-2d8026ddcc9b"
}
}
}
}
}
}
},
"securitySchemes": {
"IAM": {
"type": "apiKey",
"name": "Authorization",
"in": "header"
}
},
"schemas": {
"BaseAdvancedRulesModel": {
"allOf": [
{
"$ref": "#/components/schemas/ModelMetadata"
},
{
"description": "The advanced rules feature is deprecated. Existing models are supported until 24 June 2021, but after 10 June 2021, you will not be able to deploy advanced rules models to Natural Language Understanding. After 24 June 2021, advanced rules models will not run in Natural Language Understanding.\n\nAdvanced rules model",
"type": "object",
"properties": {
"features": {
"type": "array",
"description": "The service features that are supported by the custom model",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"description": "When the status is `available`, the model is ready to use",
"enum": [
"starting",
"training",
"deploying",
"available",
"error",
"deleted"
]
},
"model_id": {
"type": "string",
"description": "Unique model ID"
},
"workspace_id": {
"description": "ID of the Watson Knowledge Studio workspace that deployed this model to Natural Language Understanding",
"type": "string"
},
"created": {
"description": "dateTime indicating when the model was created",
"type": "string",
"format": "date-time"
},
"notices": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Notice"
},
"example": [
{
"message": "Training data validation failed: Too few examples for label insufficient_examples. Minimum of 5 required"
},
{
"message": "Not enough examples for class 'foo'. 4 were given but 5 are required."
},
{
"message": "Duplicate label given in example 27: {'foo', 'bar', 'foo'}"
}
]
},
"last_trained": {
"description": "dateTime of last successful model training",
"type": "string",
"format": "date-time"
},
"last_deployed": {
"description": "dateTime of last successful model deployment",
"type": "string",
"format": "date-time"
}
}
}
]
},
"AdvancedRulesModel": {
"allOf": [
{
"$ref": "#/components/schemas/BaseAdvancedRulesModel"
},
{
"required": [
"language",
"model_id",
"status",
"created"
]
}
]
},
"AdvancedRulesModelList": {
"description": "The advanced rules feature is deprecated. Existing models are supported until 24 June 2021, but after 10 June 2021, you will not be able to deploy advanced rules models to Natural Language Understanding. After 24 June 2021, advanced rules models will not run in Natural Language Understanding.\n\nList of advanced rules models.",
"type": "object",
"properties": {
"models": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AdvancedRulesModel"
},
"description": "The advanced rules models"
}
}
},
"AdvancedRulesAnalysisResults": {},
"FileAndMetadata": {
"allOf": [
{
"$ref": "#/components/schemas/ModelMetadata"
},
{
"type": "object",
"properties": {
"model": {
"type": "string",
"description": "The advanced rules feature is deprecated. Existing models are supported until 24 June 2021, but after 10 June 2021, you will not be able to deploy advanced rules models to Natural Language Understanding. After 24 June 2021, advanced rules models will not run in Natural Language Understanding.\n\nModel file exported from the advanced rules editor in Watson Knowledge Studio. For more information, see [Creating an advanced rules model](https://cloud.ibm.com/docs/watson-knowledge-studio?topic=watson-knowledge-studio-create-advanced-rules-model#create-advanced-rules-model-procedure).",
"format": "binary",
"x-file-content-types": [
"csv",
"zip"
]
}
}
}
]
},
"Parameters": {
"description": "An object containing request parameters",
"type": "object",
"required": [
"features"
],
"properties": {
"text": {
"description": "The plain text to analyze. One of the `text`, `html`, or `url` parameters is required.",
"type": "string"
},
"html": {
"description": "The HTML file to analyze. One of the `text`, `html`, or `url` parameters is required.",
"type": "string"
},
"url": {
"description": "The webpage to analyze. One of the `text`, `html`, or `url` parameters is required.",
"type": "string"
},
"features": {
"allOf": [
{
"$ref": "#/components/schemas/Features"
},
{
"description": "Specific features to analyze the document for"
}
]
},
"clean": {
"description": "Set this to `false` to disable webpage cleaning. For more information about webpage cleaning, see [Analyzing webpages](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-analyzing-webpages).",
"type": "boolean",
"default": true
},
"xpath": {
"type": "string",
"description": "An [XPath query](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-analyzing-webpages#xpath) to perform on `html` or `url` input. Results of the query will be appended to the cleaned webpage text before it is analyzed. To analyze only the results of the XPath query, set the `clean` parameter to `false`."
},
"fallback_to_raw": {
"type": "boolean",
"description": "Whether to use raw HTML content if text cleaning fails",
"default": true
},
"return_analyzed_text": {
"type": "boolean",
"description": "Whether or not to return the analyzed text",
"default": false
},
"language": {
"type": "string",
"description": "ISO 639-1 code that specifies the language of your text. This overrides automatic language detection. Language support differs depending on the features you include in your analysis. For more information, see [Language support](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-language-support)."
},
"limit_text_characters": {
"type": "integer",
"description": "Sets the maximum number of characters that are processed by the service."
},
"advanced_rules.model": {
"type": "string",
"deprecated": true,
"description": "The advanced rules feature is deprecated. Existing models are supported until 24 June 2021, but after 10 June 2021, you will not be able to deploy advanced rules models to Natural Language Understanding. After 24 June 2021, advanced rules models will not run in Natural Language Understanding.\n\nAn advanced rules model ID",
"x-sdk-exclude": true
}
},
"x-java-builder": true
},
"Features": {
"description": "Analysis features and options",
"type": "object",
"properties": {
"classifications": {
"$ref": "#/components/schemas/ClassificationsOptions"
},
"concepts": {
"$ref": "#/components/schemas/ConceptsOptions"
},
"emotion": {
"$ref": "#/components/schemas/EmotionOptions"
},
"entities": {
"$ref": "#/components/schemas/EntitiesOptions"
},
"keywords": {
"$ref": "#/components/schemas/KeywordsOptions"
},
"metadata": {
"$ref": "#/components/schemas/MetadataOptions"
},
"relations": {
"$ref": "#/components/schemas/RelationsOptions"
},
"semantic_roles": {
"$ref": "#/components/schemas/SemanticRolesOptions"
},
"sentiment": {
"$ref": "#/components/schemas/SentimentOptions"
},
"summarization": {
"$ref": "#/components/schemas/SummarizationOptions"
},
"categories": {
"$ref": "#/components/schemas/CategoriesOptions"
},
"syntax": {
"$ref": "#/components/schemas/SyntaxOptions"
}
},
"x-java-builder": true
},
"ListModelsResults": {
"description": "Custom models that are available for entities and relations",
"type": "object",
"properties": {
"models": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Model"
},
"description": "An array of available models"
}
}
},
"DeleteModelResults": {
"description": "Delete model results",
"properties": {
"deleted": {
"type": "string",
"description": "model_id of the deleted model"
}
}
},
"SentimentModel": {
"type": "object",
"properties": {
"features": {
"type": "array",
"description": "The service features that are supported by the custom model",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"description": "When the status is `available`, the model is ready to use",
"enum": [
"starting",
"training",
"deploying",
"available",
"error",
"deleted"
]
},
"model_id": {
"type": "string",
"description": "Unique model ID"
},
"created": {
"description": "dateTime indicating when the model was created",
"type": "string",
"format": "date-time"
},
"last_trained": {
"description": "dateTime of last successful model training",
"type": "string",
"format": "date-time"
},
"last_deployed": {
"description": "dateTime of last successful model deployment",
"type": "string",
"format": "date-time"
},
"name": {
"type": "string",
"description": "A name for the model"
},
"user_metadata": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "integer"
},
{
"type": "boolean"
}
]
},
"example": {
"region": "North America",
"latest": true
},
"description": "An optional map of metadata key-value pairs to store with this model"
},
"language": {
"type": "string",
"description": "The 2-letter language code of this model"
},
"description": {
"type": "string",
"description": "An optional description of the model"
},
"model_version": {
"type": "string",
"description": "An optional version string"
},
"notices": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Notice"
},
"example": [
{
"message": "Training data validation failed: Too few examples for label insufficient_examples. Minimum of 5 required"
},
{
"message": "Not enough examples for class 'foo'. 4 were given but 5 are required."
},
{
"message": "Duplicate label given in example 27: {'foo', 'bar', 'foo'}"
}
]
},
"version": {
"type": "string",
"deprecated": true,
"description": "Deprecated — use `model_version`",
"x-sdk-exclude": true
},
"workspace_id": {
"type": "string",
"description": "ID of the Watson Knowledge Studio workspace that deployed this model to Natural Language Understanding",
"nullable": true
},
"version_description": {
"type": "string",
"description": "The description of the version",
"nullable": true
}
}
},
"Model": {
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "When the status is `available`, the model is ready to use",
"enum": [
"starting",
"training",
"deploying",
"available",
"error",
"deleted"
]
},
"model_id": {
"type": "string",
"description": "Unique model ID"
},
"language": {
"type": "string",
"description": "ISO 639-1 code that indicates the language of the model"
},
"description": {
"type": "string",
"description": "Model description"
},
"workspace_id": {
"description": "ID of the Watson Knowledge Studio workspace that deployed this model to Natural Language Understanding",
"type": "string"
},
"model_version": {
"description": "The model version, if it was manually provided in Watson Knowledge Studio",
"type": "string"
},
"version": {
"description": "Deprecated — use `model_version`",
"type": "string",
"deprecated": true
},
"version_description": {
"description": "The description of the version, if it was manually provided in Watson Knowledge Studio",
"type": "string"
},
"created": {
"description": "A dateTime indicating when the model was created",
"type": "string",
"format": "date-time"
}
}
},
"SentimentModelFileAndMetadata": {
"allOf": [
{
"$ref": "#/components/schemas/ModelMetadata"
},
{
"type": "object",
"properties": {
"training_data": {
"type": "string",
"description": "Training data in CSV format. For more information, see [Sentiment training data requirements](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-custom-sentiment#sentiment-training-data-requirements).",
"format": "binary",
"x-file-content-types": [
"text/csv"
]
}
},
"required": [
"training_data"
]
}
]
},
"ModelFileAndMetadata": {
"allOf": [
{
"$ref": "#/components/schemas/ModelMetadata"
},
{
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary",
"x-file-content-types": [
"csv",
"zip"
]
}
},
"required": [
"file"
]
}
]
},
"ModelMetadata": {
"description": "Metadata associated with this custom model",
"type": "object",
"required": [
"language"
],
"properties": {
"name": {
"type": "string",
"description": "An optional name for the model"
},
"user_metadata": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "integer"
},
{
"type": "boolean"
}
]
},
"example": {
"region": "North America",
"latest": true
},
"description": "An optional map of metadata key-value pairs to store with this model"
},
"language": {
"type": "string",
"description": "The 2-letter language code of this model"
},
"description": {
"type": "string",
"description": "An optional description of the model"
},
"model_version": {
"type": "string",
"description": "An optional version string"
},
"version": {
"type": "string",
"deprecated": true,
"description": "Deprecated — use `model_version`",
"x-sdk-exclude": true
},
"workspace_id": {
"type": "string",
"description": "ID of the Watson Knowledge Studio workspace that deployed this model to Natural Language Understanding",
"nullable": true
},
"version_description": {
"type": "string",
"description": "The description of the version",
"nullable": true
}
}
},
"AnalysisResults": {
"description": "Results of the analysis, organized by feature",
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"language": {
"type": "string",
"description": "Language used to analyze the text"
},
"analyzed_text": {
"type": "string",
"description": "Text that was used in the analysis"
},
"retrieved_url": {
"type": "string",
"description": "URL of the webpage that was analyzed"
},
"usage": {
"allOf": [
{
"$ref": "#/components/schemas/Usage"
},
{
"type": "object",
"description": "API usage information for the request"
}
]
},
"advanced_rules": {
"deprecated": true,
"description": "The advanced rules feature is deprecated. Existing models are supported until 24 June 2021, but after 10 June 2021, you will not be able to deploy advanced rules models to Natural Language Understanding. After 24 June 2021, advanced rules models will not run in Natural Language Understanding.\n\nResponse from advanced rules analysis",
"type": "object",
"additionalProperties": {
"description": "The keys and values from the text extractor in the exported model file from Watson Knowledge Studio. For more information about the format, see [Output format for advanced rules analysis](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-customizing#advanced-rules-analysis-output)."
},
"example": {
"Country": [
{
"Country": {
"text": "USA",
"location": {
"end": 23,
"begin": 20
}
},
"Continent": null
}
]
},
"x-sdk-exclude": true
}
}
},
{
"$ref": "#/components/schemas/FeaturesResults"
}
]
},
"Usage": {
"description": "Usage information",
"type": "object",
"properties": {
"features": {
"type": "integer",
"description": "Number of features used in the API call"
},
"text_characters": {
"type": "integer",
"description": "Number of text characters processed"
},
"text_units": {
"type": "integer",
"description": "Number of 10,000-character units processed"
}
}
},
"Notice": {
"type": "object",
"description": "A list of messages describing model training issues when model status is `error`",
"properties": {
"message": {
"type": "string",
"readOnly": true,
"description": "Describes deficiencies or inconsistencies in training data"
}
}
},
"FeaturesResults": {
"description": "Analysis results for each requested feature",
"type": "object",
"properties": {
"concepts": {
"description": "The general concepts referenced or alluded to in the analyzed text",
"type": "array",
"items": {
"$ref": "#/components/schemas/ConceptsResult"
},
"example": [
{
"text": "Social network service",
"relevance": 0.92186,
"dbpedia_resource": "http://dbpedia.org/resource/Social_network_service"
},
{
"text": "Thomas J. Watson",
"relevance": 0.871908,
"dbpedia_resource": "http://dbpedia.org/resource/Thomas_J._Watson"
},
{
"text": "Lotus Software",
"relevance": 0.839578,
"dbpedia_resource": "http://dbpedia.org/resource/Lotus_Software"
}
]
},
"entities": {
"description": "The entities detected in the analyzed text",
"type": "array",
"items": {
"$ref": "#/components/schemas/EntitiesResult"
},
"example": [
{
"text": "Social network service",
"relevance": 0.92186,
"dbpedia_resource": "http://dbpedia.org/resource/Social_network_service"
},
{
"text": "Thomas J. Watson",
"relevance": 0.871908,
"dbpedia_resource": "http://dbpedia.org/resource/Thomas_J._Watson"
},
{
"text": "Lotus Software",
"relevance": 0.839578,
"dbpedia_resource": "http://dbpedia.org/resource/Lotus_Software"
}
]
},
"keywords": {
"description": "The keywords from the analyzed text",
"type": "array",
"items": {
"$ref": "#/components/schemas/KeywordsResult"
},
"example": [
{
"text": "curated online courses",
"sentiment": {
"score": 0.792454
},
"relevance": 0.864624,
"emotion": {
"sadness": 0.188625,
"joy": 0.522781,
"fear": 0.12012,
"disgust": 0.103212,
"anger": 0.106669
},
"count": 1
},
{
"text": "free virtual server",
"sentiment": {
"score": 0.664726
},
"relevance": 0.864593,
"emotion": {
"sadness": 0.265225,
"joy": 0.532354,
"fear": 0.07773,
"disgust": 0.090112,
"anger": 0.102242
},
"count": 1
}
]
},
"categories": {
"description": "The categories that the service assigned to the analyzed text.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CategoriesResult"
},
"example": [
{
"score": 0.594296,
"label": "/technology and computing/computing/computer software and applications"
},
{
"score": 0.448495,
"label": "/science"
},
{
"score": 0.426429,
"label": "/business and finance/industries"
}
]
},
"classifications": {
"description": "The classifications assigned to the analyzed text.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ClassificationsResult"
},
"example": [
{
"class_name": "temperature",
"confidence": 0.562519
},
{
"class_name": "conditions",
"confidence": 0.433996
}
]
},
"emotion": {
"allOf": [
{
"$ref": "#/components/schemas/EmotionResult"
},
{
"description": "The anger, disgust, fear, joy, or sadness conveyed by the content"
}
]
},
"metadata": {
"allOf": [
{
"$ref": "#/components/schemas/MetadataResult"
},
{
"description": "Webpage metadata, such as the author and the title of the page",
"type": "object"
}
]
},
"relations": {
"description": "The relationships between entities in the content",
"type": "array",
"items": {
"$ref": "#/components/schemas/RelationsResult"
},
"example": [
{
"type": "awardedTo",
"sentence": "Leonardo DiCaprio won Best Actor in a Leading Role for his performance.",
"score": 0.680715,
"arguments": [
{
"text": "Best Actor",
"location": [
22,
32
],
"entities": [
{
"type": "EntertainmentAward",
"text": "Best Actor"
}
]
},
{
"text": "Leonardo DiCaprio",
"location": [
0,
17
],
"entities": [
{
"type": "Person",
"text": "Leonardo DiCaprio"
}
]
}
]
}
]
},
"semantic_roles": {
"description": "Sentences parsed into `subject`, `action`, and `object` form.",
"type": "array",
"items": {
"$ref": "#/components/schemas/SemanticRolesResult"
},
"example": [
{
"subject": {
"text": "IBM"
},
"sentence": "IBM has one of the largest workforces in the world",
"object": {
"text": "one of the largest workforces in the world"
},
"action": {
"verb": {
"text": "have",
"tense": "present"
},
"text": "has",
"normalized": "have"
}
}
]
},
"sentiment": {
"allOf": [
{
"$ref": "#/components/schemas/SentimentResult"
},
{
"description": "The sentiment of the content"
}
]
},
"summarization": {
"$ref": "#/components/schemas/SummarizationResult"
},
"syntax": {
"$ref": "#/components/schemas/SyntaxResult"
}
}
},
"ConceptsResult": {
"description": "The general concepts referenced or alluded to in the analyzed text",
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "Name of the concept"
},
"relevance": {
"type": "number",
"format": "double",
"description": "Relevance score between 0 and 1. Higher scores indicate greater relevance"
},
"dbpedia_resource": {
"allOf": [
{
"$ref": "#/components/schemas/DBpediaResource"
},
{
"description": "Link to the corresponding DBpedia resource"
}
]
}
}
},
"DBpediaResource": {
"type": "string",
"description": "Link to the corresponding DBpedia resource"
},
"DisambiguationResult": {
"description": "Disambiguation information for the entity",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Common entity name"
},
"dbpedia_resource": {
"allOf": [
{
"$ref": "#/components/schemas/DBpediaResource"
},
{
"description": "Link to the corresponding DBpedia resource"
}
]
},
"subtype": {
"type": "array",
"description": "Entity subtype information",
"items": {
"type": "string"
}
}
}
},
"EntitiesResult": {
"description": "The important people, places, geopolitical entities and other types of entities in your content",
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Entity type"
},
"text": {
"type": "string",
"description": "The name of the entity"
},
"relevance": {
"type": "number",
"format": "double",
"description": "Relevance score from 0 to 1. Higher values indicate greater relevance"
},
"confidence": {
"type": "number",
"format": "double",
"description": "Confidence in the entity identification from 0 to 1. Higher values indicate higher confidence. In standard entities requests, confidence is returned only for English text. All entities requests that use custom models return the confidence score."
},
"mentions": {
"type": "array",
"description": "Entity mentions and locations",
"items": {
"$ref": "#/components/schemas/EntityMention"
}
},
"count": {
"type": "integer",
"description": "How many times the entity was mentioned in the text"
},
"emotion": {
"allOf": [
{
"$ref": "#/components/schemas/EmotionScores"
},
{
"description": "Emotion analysis results for the entity, enabled with the `emotion` option"
}
]
},
"sentiment": {
"allOf": [
{
"$ref": "#/components/schemas/FeatureSentimentResults"
},
{
"description": "Sentiment analysis results for the entity, enabled with the `sentiment` option"
}
]
},
"disambiguation": {
"allOf": [
{
"$ref": "#/components/schemas/DisambiguationResult"
},
{
"description": "Disambiguation information for the entity"
}
]
}
}
},
"EntityMention": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "Entity mention text"
},
"location": {
"type": "array",
"description": "Character offsets indicating the beginning and end of the mention in the analyzed text",
"items": {
"type": "integer"
}
},
"confidence": {
"type": "number",
"format": "double",
"description": "Confidence in the entity identification from 0 to 1. Higher values indicate higher confidence. In standard entities requests, confidence is returned only for English text. All entities requests that use custom models return the confidence score."
}
}
},
"KeywordsResult": {
"type": "object",
"description": "The important keywords in the content, organized by relevance",
"properties": {
"count": {
"type": "integer",
"description": "Number of times the keyword appears in the analyzed text"
},
"relevance": {
"type": "number",
"format": "double",
"description": "Relevance score from 0 to 1. Higher values indicate greater relevance"
},
"text": {
"type": "string",
"description": "The keyword text"
},
"emotion": {
"allOf": [
{
"$ref": "#/components/schemas/EmotionScores"
},
{
"description": "Emotion analysis results for the keyword, enabled with the `emotion` option"
}
]
},
"sentiment": {
"allOf": [
{
"$ref": "#/components/schemas/FeatureSentimentResults"
},
{
"description": "Sentiment analysis results for the keyword, enabled with the `sentiment` option"
}
]
}
}
},
"CategoriesResult": {
"description": "A categorization of the analyzed text",
"type": "object",
"properties": {
"label": {
"type": "string",
"description": "The path to the category through the multi-level taxonomy hierarchy. For more information about the categories, see [Categories hierarchy](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-categories#categories-hierarchy)."
},
"score": {
"type": "number",
"format": "double",
"description": "Confidence score for the category classification. Higher values indicate greater confidence."
},
"explanation": {
"description": "Information that helps to explain what contributed to the categories result.",
"type": "object",
"properties": {
"relevant_text": {
"description": "An array of relevant text from the source that contributed to the categorization. The sorted array begins with the phrase that contributed most significantly to the result, followed by phrases that were less and less impactful.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CategoriesRelevantText"
}
}
}
}
}
},
"CategoriesRelevantText": {
"description": "Relevant text that contributed to the categorization.",
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "Text from the analyzed source that supports the categorization."
}
}
},
"ClassificationsResult": {
"description": "A classification of the analyzed text",
"type": "object",
"properties": {
"class_name": {
"type": "string",
"description": "Classification assigned to the text."
},
"confidence": {
"type": "number",
"format": "double",
"description": "Confidence score for the classification. Higher values indicate greater confidence."
}
}
},
"EmotionResult": {
"type": "object",
"description": "The detected anger, disgust, fear, joy, or sadness that is conveyed by the content. Emotion information can be returned for detected entities, keywords, or user-specified target phrases found in the text",
"properties": {
"document": {
"allOf": [
{
"$ref": "#/components/schemas/DocumentEmotionResults"
},
{
"description": "Emotion results for the document as a whole"
}
]
},
"targets": {
"type": "array",
"description": "Emotion results for specified targets",
"items": {
"$ref": "#/components/schemas/TargetedEmotionResults"
}
}
},
"example": {
"targets": [
{
"text": "apples",
"emotion": {
"sadness": 0.028574,
"joy": 0.859042,
"fear": 0.02752,
"disgust": 0.017519,
"anger": 0.012855
}
},
{
"text": "oranges",
"emotion": {
"sadness": 0.514253,
"joy": 0.078317,
"fear": 0.074223,
"disgust": 0.058103,
"anger": 0.126859
}
}
],
"document": {
"emotion": {
"sadness": 0.32665,
"joy": 0.563273,
"fear": 0.033387,
"disgust": 0.022637,
"anger": 0.041796
}
}
}
},
"DocumentEmotionResults": {
"type": "object",
"description": "Emotion results for the document as a whole",
"properties": {
"emotion": {
"allOf": [
{
"$ref": "#/components/schemas/EmotionScores"
},
{
"description": "Emotion results for the document as a whole"
}
]
}
}
},
"TargetedEmotionResults": {
"type": "object",
"description": "Emotion results for a specified target",
"properties": {
"text": {
"type": "string",
"description": "Targeted text"
},
"emotion": {
"allOf": [
{
"$ref": "#/components/schemas/EmotionScores"
},
{
"description": "The emotion results for the target"
}
]
}
}
},
"EmotionScores": {
"type": "object",
"properties": {
"anger": {
"type": "number",
"format": "double",
"description": "Anger score from 0 to 1. A higher score means that the text is more likely to convey anger"
},
"disgust": {
"type": "number",
"format": "double",
"description": "Disgust score from 0 to 1. A higher score means that the text is more likely to convey disgust"
},
"fear": {
"type": "number",
"format": "double",
"description": "Fear score from 0 to 1. A higher score means that the text is more likely to convey fear"
},
"joy": {
"type": "number",
"format": "double",
"description": "Joy score from 0 to 1. A higher score means that the text is more likely to convey joy"
},
"sadness": {
"type": "number",
"format": "double",
"description": "Sadness score from 0 to 1. A higher score means that the text is more likely to convey sadness"
}
}
},
"MetadataResult": {
"description": "The authors, publication date, title, prominent page image, and RSS/ATOM feeds of the webpage. Supports URL and HTML input types",
"type": "object",
"properties": {
"authors": {
"type": "array",
"description": "The authors of the document",
"items": {
"$ref": "#/components/schemas/Author"
}
},
"publication_date": {
"type": "string",
"description": "The publication date in the format ISO 8601"
},
"title": {
"type": "string",
"description": "The title of the document"
},
"image": {
"type": "string",
"description": "URL of a prominent image on the webpage"
},
"feeds": {
"type": "array",
"description": "RSS/ATOM feeds found on the webpage",
"items": {
"$ref": "#/components/schemas/Feed"
}
}
},
"example": {
"title": "IBM - United States",
"publication_date": "2015-10-01T00:00:00",
"image": "",
"feeds": [],
"authors": []
}
},
"Author": {
"type": "object",
"description": "The author of the analyzed content",
"properties": {
"name": {
"type": "string",
"description": "Name of the author"
}
}
},
"Feed": {
"type": "object",
"description": "RSS or ATOM feed found on the webpage",
"properties": {
"link": {
"type": "string",
"description": "URL of the RSS or ATOM feed"
}
}
},
"RelationsResult": {
"type": "object",
"description": "The relations between entities found in the content",
"properties": {
"score": {
"type": "number",
"format": "double",
"description": "Confidence score for the relation. Higher values indicate greater confidence."
},
"sentence": {
"type": "string",
"description": "The sentence that contains the relation"
},
"type": {
"type": "string",
"description": "The type of the relation"
},
"arguments": {
"type": "array",
"description": "Entity mentions that are involved in the relation",
"items": {
"$ref": "#/components/schemas/RelationArgument"
}
}
}
},
"RelationArgument": {
"type": "object",
"properties": {
"entities": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RelationEntity"
},
"description": "An array of extracted entities"
},
"location": {
"type": "array",
"description": "Character offsets indicating the beginning and end of the mention in the analyzed text",
"items": {
"type": "integer"
}
},
"text": {
"type": "string",
"description": "Text that corresponds to the argument"
}
}
},
"RelationEntity": {
"type": "object",
"description": "An entity that corresponds with an argument in a relation",
"properties": {
"text": {
"type": "string",
"description": "Text that corresponds to the entity"
},
"type": {
"type": "string",
"description": "Entity type"
}
}
},
"SemanticRolesResult": {
"type": "object",
"description": "The object containing the actions and the objects the actions act upon",
"properties": {
"sentence": {
"type": "string",
"description": "Sentence from the source that contains the subject, action, and object"
},
"subject": {
"allOf": [
{
"$ref": "#/components/schemas/SemanticRolesSubject"
},
{
"type": "object",
"description": "The extracted subject from the sentence"
}
]
},
"action": {
"allOf": [
{
"$ref": "#/components/schemas/SemanticRolesAction"
},
{
"type": "object",
"description": "The extracted action from the sentence"
}
]
},
"object": {
"allOf": [
{
"$ref": "#/components/schemas/SemanticRolesObject"
},
{
"type": "object",
"description": "The extracted object from the sentence"
}
]
}
}
},
"SemanticRolesEntity": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Entity type"
},
"text": {
"type": "string",
"description": "The entity text"
}
}
},
"SemanticRolesKeyword": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "The keyword text"
}
}
},
"SemanticRolesSubject": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "Text that corresponds to the subject role"
},
"entities": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SemanticRolesEntity"
},
"description": "An array of extracted entities"
},
"keywords": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SemanticRolesKeyword"
},
"description": "An array of extracted keywords"
}
}
},
"SemanticRolesAction": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "Analyzed text that corresponds to the action"
},
"normalized": {
"type": "string",
"description": "normalized version of the action"
},
"verb": {
"$ref": "#/components/schemas/SemanticRolesVerb"
}
}
},
"SemanticRolesObject": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "Object text"
},
"keywords": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SemanticRolesKeyword"
},
"description": "An array of extracted keywords"
}
}
},
"SemanticRolesVerb": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "The keyword text"
},
"tense": {
"type": "string",
"description": "Verb tense"
}
}
},
"SentimentResult": {
"type": "object",
"description": "The sentiment of the content",
"properties": {
"document": {
"allOf": [
{
"$ref": "#/components/schemas/DocumentSentimentResults"
},
{
"description": "The document level sentiment"
}
]
},
"targets": {
"type": "array",
"description": "The targeted sentiment to analyze",
"items": {
"$ref": "#/components/schemas/TargetedSentimentResults"
}
}
},
"example": {
"targets": [
{
"text": "stocks",
"score": 0.279964,
"label": "positive"
}
],
"document": {
"score": 0.127034,
"label": "positive"
}
}
},
"DocumentSentimentResults": {
"type": "object",
"properties": {
"label": {
"type": "string",
"description": "Indicates whether the sentiment is positive, neutral, or negative"
},
"score": {
"type": "number",
"format": "double",
"description": "Sentiment score from -1 (negative) to 1 (positive)"
}
}
},
"FeatureSentimentResults": {
"type": "object",
"properties": {
"score": {
"type": "number",
"format": "double",
"description": "Sentiment score from -1 (negative) to 1 (positive)"
}
}
},
"TargetedSentimentResults": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "Targeted text"
},
"score": {
"type": "number",
"format": "double",
"description": "Sentiment score from -1 (negative) to 1 (positive)"
}
}
},
"SyntaxResult": {
"description": "Tokens and sentences returned from syntax analysis.",
"type": "object",
"properties": {
"tokens": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenResult"
}
},
"sentences": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SentenceResult"
}
}
}
},
"SummarizationResult": {
"description": "(Experimental) Summary of content",
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "Summary sentences of input source"
}
},
"example": {
"text": "Today, IBM and Workday, a leading provider of enterprise applications for human resources and finance, announced a joint solution designed to help companies begin the process of safely re-opening their workplaces. Here are five key takeaways from the announcement. The two companies, which have had a partnership since 2011, announced a new solution to help businesses and communities determine when and how to safely open up their workplaces during the ongoing COVID-19 pandemic."
},
"x-sdk-exclude": true
},
"TokenResult": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "The token as it appears in the analyzed text."
},
"part_of_speech": {
"type": "string",
"description": "The part of speech of the token. For more information about the values, see [Universal Dependencies POS tags](https://universaldependencies.org/u/pos/).",
"enum": [
"ADJ",
"ADP",
"ADV",
"AUX",
"CCONJ",
"DET",
"INTJ",
"NOUN",
"NUM",
"PART",
"PRON",
"PROPN",
"PUNCT",
"SCONJ",
"SYM",
"VERB",
"X"
]
},
"location": {
"type": "array",
"description": "Character offsets indicating the beginning and end of the token in the analyzed text.",
"items": {
"type": "integer"
}
},
"lemma": {
"type": "string",
"description": "The [lemma](https://wikipedia.org/wiki/Lemma_%28morphology%29) of the token."
}
}
},
"SentenceResult": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "The sentence."
},
"location": {
"type": "array",
"description": "Character offsets indicating the beginning and end of the sentence in the analyzed text.",
"items": {
"type": "integer"
}
}
}
},
"ConceptsOptions": {
"type": "object",
"description": "Returns high-level concepts in the content. For example, a research paper about deep learning might return the concept, \"Artificial Intelligence\" although the term is not mentioned.\n\nSupported languages: English, French, German, Italian, Japanese, Korean, Portuguese, Spanish.",
"properties": {
"limit": {
"type": "integer",
"default": 8,
"description": "Maximum number of concepts to return.",
"maximum": 50
}
},
"example": {
"limit": 3
},
"x-java-builder": true
},
"EmotionOptions": {
"type": "object",
"description": "Detects anger, disgust, fear, joy, or sadness that is conveyed in the content or by the context around target phrases specified in the targets parameter. You can analyze emotion for detected entities with `entities.emotion` and for keywords with `keywords.emotion`.\n\nSupported languages: English",
"properties": {
"document": {
"type": "boolean",
"default": true,
"description": "Set this to `false` to hide document-level emotion results"
},
"targets": {
"type": "array",
"items": {
"type": "string"
},
"description": "Emotion results will be returned for each target string that is found in the document"
}
},
"example": {
"targets": [
"apples",
"oranges"
]
},
"x-java-builder": true
},
"EntitiesOptions": {
"type": "object",
"description": "Identifies people, cities, organizations, and other entities in the content. For more information, see [Entity types and subtypes](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-entity-type-systems).\n\nSupported languages: English, French, German, Italian, Japanese, Korean, Portuguese, Russian, Spanish, Swedish. Arabic, Chinese, and Dutch are supported only through custom models.",
"properties": {
"limit": {
"type": "integer",
"default": 50,
"description": "Maximum number of entities to return.",
"maximum": 250
},
"mentions": {
"type": "boolean",
"default": false,
"description": "Set this to `true` to return locations of entity mentions"
},
"model": {
"type": "string",
"description": "Enter a [custom model](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-customizing) ID to override the standard entity detection model"
},
"sentiment": {
"type": "boolean",
"default": false,
"description": "Set this to `true` to return sentiment information for detected entities"
},
"emotion": {
"type": "boolean",
"default": false,
"description": "Set this to `true` to analyze emotion for detected keywords"
}
},
"example": {
"sentiment": true,
"limit": 1
},
"x-java-builder": true
},
"KeywordsOptions": {
"type": "object",
"description": "Returns important keywords in the content.\n\nSupported languages: English, French, German, Italian, Japanese, Korean, Portuguese, Russian, Spanish, Swedish.",
"properties": {
"limit": {
"type": "integer",
"default": 50,
"description": "Maximum number of keywords to return",
"maximum": 250
},
"sentiment": {
"type": "boolean",
"default": false,
"description": "Set this to `true` to return sentiment information for detected keywords"
},
"emotion": {
"type": "boolean",
"default": false,
"description": "Set this to `true` to analyze emotion for detected keywords"
}
},
"example": {
"sentiment": true,
"emotion": true,
"limit": 3
},
"x-java-builder": true
},
"MetadataOptions": {
"type": "object",
"description": "Returns information from the document, including author name, title, RSS/ATOM feeds, prominent page image, and publication date. Supports URL and HTML input types only.",
"properties": {},
"additionalProperties": true
},
"RelationsOptions": {
"type": "object",
"description": "Recognizes when two entities are related and identifies the type of relation. For example, an `awardedTo` relation might connect the entities \"Nobel Prize\" and \"Albert Einstein\". For more information, see [Relation types](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-relations).\n\nSupported languages: Arabic, English, German, Japanese, Korean, Spanish. Chinese, Dutch, French, Italian, and Portuguese custom models are also supported.",
"properties": {
"model": {
"type": "string",
"description": "Enter a [custom model](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-customizing) ID to override the default model"
}
},
"x-java-builder": true
},
"SemanticRolesOptions": {
"type": "object",
"description": "Parses sentences into subject, action, and object form.\n\nSupported languages: English, German, Japanese, Korean, Spanish.",
"properties": {
"limit": {
"type": "integer",
"description": "Maximum number of semantic_roles results to return",
"default": 50
},
"keywords": {
"type": "boolean",
"description": "Set this to `true` to return keyword information for subjects and objects",
"default": false
},
"entities": {
"type": "boolean",
"description": "Set this to `true` to return entity information for subjects and objects",
"default": false
}
},
"example": {
"keywords": true,
"entities": true
},
"x-java-builder": true
},
"SentimentOptions": {
"type": "object",
"description": "Analyzes the general sentiment of your content or the sentiment toward specific target phrases. You can analyze sentiment for detected entities with `entities.sentiment` and for keywords with `keywords.sentiment`.\n\n Supported languages: Arabic, English, French, German, Italian, Japanese, Korean, Portuguese, Russian, Spanish",
"properties": {
"document": {
"type": "boolean",
"default": true,
"description": "Set this to `false` to hide document-level sentiment results"
},
"targets": {
"type": "array",
"items": {
"type": "string"
},
"description": "Sentiment results will be returned for each target string that is found in the document"
}
},
"example": {
"targets": [
"stocks"
]
},
"x-java-builder": true
},
"CategoriesModel": {
"description": "Categories model",
"allOf": [
{
"$ref": "#/components/schemas/BaseAdvancedRulesModel"
},
{
"required": [
"language",
"model_id",
"status",
"created"
]
}
]
},
"CategoriesModelList": {
"description": "List of categories models.",
"type": "object",
"properties": {
"models": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CategoriesModel"
},
"description": "The categories models"
}
}
},
"CategoriesModelFileAndMetadata": {
"allOf": [
{
"$ref": "#/components/schemas/ModelMetadata"
},
{
"type": "object",
"properties": {
"training_data": {
"type": "string",
"description": "Training data in JSON format. For more information, see [Categories training data requirements](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-categories##categories-training-data-requirements).",
"format": "binary",
"x-file-content-types": [
"json",
"application/json"
]
}
},
"required": [
"training_data"
]
}
]
},
"CategoriesOptions": {
"type": "object",
"description": "Returns a hierarchical taxonomy of the content. The top three categories are returned by default. \n\nSupported languages: Arabic, English, French, German, Italian, Japanese, Korean, Portuguese, Spanish.",
"properties": {
"explanation": {
"description": "Set this to `true` to return explanations for each categorization. **This is available only for English categories.**",
"type": "boolean",
"default": false
},
"limit": {
"description": "Maximum number of categories to return.",
"type": "integer",
"default": 3,
"maximum": 10
},
"model": {
"description": "(Beta) Enter a [custom model](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-customizing) ID to override the standard categories model. **This is available only for English categories.**",
"type": "string"
}
},
"x-java-builder": true
},
"ClassificationsModel": {
"description": "Classifications model",
"allOf": [
{
"$ref": "#/components/schemas/BaseAdvancedRulesModel"
},
{
"required": [
"language",
"model_id",
"status",
"created"
]
}
]
},
"ClassificationsModelList": {
"description": "List of classifications models.",
"type": "object",
"properties": {
"models": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ClassificationsModel"
},
"description": "The classifications models"
}
}
},
"ClassificationsModelFileMetadataAndTrainingParameters": {
"allOf": [
{
"$ref": "#/components/schemas/ClassificationsModelFileAndMetadata"
},
{
"type": "object",
"properties": {
"training_parameters": {
"$ref": "#/components/schemas/ClassificationsTrainingParameters"
}
}
}
]
},
"ClassificationsModelFileAndMetadata": {
"allOf": [
{
"$ref": "#/components/schemas/ModelMetadata"
},
{
"type": "object",
"properties": {
"training_data": {
"type": "string",
"description": "Training data in JSON format. For more information, see [Classifications training data requirements](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-classifications#classification-training-data-requirements).",
"format": "binary",
"x-file-content-types": [
"json",
"application/json"
]
}
},
"required": [
"training_data"
]
}
]
},
"ClassificationsOptions": {
"type": "object",
"description": "Returns text classifications for the content.",
"properties": {
"model": {
"description": "Enter a [custom model](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-customizing) ID of the classifications model to be used. \n\nYou can analyze tone by using a language-specific model ID. See [Tone analytics (Classifications)](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-tone_analytics) for more information.",
"type": "string"
}
},
"x-java-builder": true
},
"SummarizationOptions": {
"description": "(Experimental) Returns a summary of content. \n\nSupported languages: English only. \n\nSupported regions: Dallas region only",
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "Maximum number of summary sentences to return",
"default": 3,
"maximum": 10
}
},
"additionalProperties": false
},
"SyntaxOptions": {
"type": "object",
"description": "Returns tokens and sentences from the input text.",
"properties": {
"tokens": {
"type": "object",
"description": "Tokenization options.",
"properties": {
"lemma": {
"type": "boolean",
"description": "Set this to `true` to return the lemma for each token."
},
"part_of_speech": {
"type": "boolean",
"description": "Set this to `true` to return the part of speech for each token."
}
}
},
"sentences": {
"type": "boolean",
"description": "Set this to `true` to return sentence information."
}
},
"example": {
"tokens": {
"lemma": true,
"part_of_speech": true
},
"sentences": true
},
"x-java-builder": true
},
"ErrorResponse": {
"type": "object",
"required": [
"code",
"error"
],
"properties": {
"code": {
"description": "The HTTP error status code",
"type": "integer"
},
"error": {
"description": "A message describing the error",
"type": "string"
}
}
},
"ClassificationsTrainingParameters": {
"type": "object",
"description": "Optional classifications training parameters along with model train requests",
"properties": {
"model_type": {
"description": "Model type selector to train either a single_label or a multi_label classifier",
"type": "string",
"enum": [
"single_label",
"multi_label"
]
}
}
}
}
}
}