{
  "swagger": "2.0",
  "info": {
    "version": "v2.1-preview",
    "contact": {
      "name": "Microsoft Cognitive Services",
      "url": "https://azure.microsoft.com/en-us/services/cognitive-services/text-analytics/",
      "email": "mlapi@microsoft.com"
    },
    "title": "Text Analytics Client",
    "description": "The Text Analytics API is a suite of text analytics web services built with best-in-class Microsoft machine learning algorithms. The API can be used to analyze unstructured text for tasks such as sentiment analysis, key phrase extraction and language detection. No training data is needed to use this API; just bring your text data. This API uses advanced natural language processing techniques to deliver best in class predictions. Further documentation can be found in https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/overview"
  },
  "securityDefinitions": {
    "apim_key": {
      "type": "apiKey",
      "name": "Ocp-Apim-Subscription-Key",
      "in": "header"
    }
  },
  "security": [
    {
      "apim_key": []
    }
  ],
  "x-ms-parameterized-host": {
    "hostTemplate": "{Endpoint}/text/analytics/v2.1-preview",
    "useSchemePrefix": false,
    "parameters": [
      {
        "$ref": "#/parameters/Endpoint"
      }
    ]
  },
  "paths": {
    "/keyPhrases": {
      "post": {
        "tags": [
          "Key Phrases"
        ],
        "summary": "The API returns a list of strings denoting the key talking points in the input text.",
        "description": "See the <a href=\"https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/overview#supported-languages\">Text Analytics Documentation</a> for details about the languages that are supported by key phrase extraction.",
        "operationId": "Key Phrases",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "input",
            "in": "body",
            "description": "Collection of documents to analyze. Documents can now contain a language field to indicate the text language",
            "required": true,
            "schema": {
              "$ref": "#/definitions/MultiLanguageBatchInput"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A successful response results in 0 or more key phrases identified in each valid document",
            "schema": {
              "$ref": "#/definitions/KeyPhraseBatchResult"
            }
          },
          "default": {
            "description": "Error Response",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        },
        "x-ms-examples": {
          "Successful Key Phrase request": {
            "$ref": "./examples//SuccessfulKeyPhrasesRequest.json"
          }
        },
        "deprecated": false
      }
    },
    "/languages": {
      "post": {
        "tags": [
          "Detect Language"
        ],
        "summary": "The API returns the detected language and a numeric score between 0 and 1.",
        "description": "Scores close to 1 indicate 100% certainty that the identified language is true. A total of 120 languages are supported.",
        "operationId": "Detect Language",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "input",
            "in": "body",
            "description": "Collection of documents to analyze.",
            "required": true,
            "schema": {
              "$ref": "#/definitions/BatchInput"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A successful call results in the detected language with the highest probability for each valid document",
            "schema": {
              "$ref": "#/definitions/LanguageBatchResult"
            }
          },
          "default": {
            "description": "Error Response",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        },
        "x-ms-examples": {
          "Successful Detect Language request": {
            "$ref": "./examples//SuccessfulLanguagesRequest.json"
          }
        },
        "deprecated": false
      }
    },
    "/sentiment": {
      "post": {
        "tags": [
          "Sentiment"
        ],
        "summary": "The API returns a numeric score between 0 and 1.",
        "description": "Scores close to 1 indicate positive sentiment, while scores close to 0 indicate negative sentiment. A score of 0.5 indicates the lack of sentiment (e.g. a factoid statement). See the <a href=\"https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/overview#supported-languages\">Text Analytics Documentation</a> for details about the languages that are supported by sentiment analysis.",
        "operationId": "Sentiment",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "input",
            "in": "body",
            "description": "Collection of documents to analyze.",
            "required": true,
            "schema": {
              "$ref": "#/definitions/MultiLanguageBatchInput"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A successful call results in each valid document getting a sentiment score between 0 and 1",
            "schema": {
              "$ref": "#/definitions/SentimentBatchResult"
            }
          },
          "default": {
            "description": "Error Response",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        },
        "x-ms-examples": {
          "Successful Sentiment request": {
            "$ref": "./examples//SuccessfulSentimentRequest.json"
          }
        },
        "deprecated": false
      }
    },
    "/entities": {
      "post": {
        "tags": [
          "Entities"
        ],
        "summary": "The API returns a list of recognized entities in a given document.",
        "description": "The API returns a list of recognized entities in a given document. To get even more information on each recognized entity we recommend using the Bing Entity Search API by querying for the recognized entities names. See the <a href=\"https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/text-analytics-supported-languages\">Supported languages in Text Analytics API</a> for the list of enabled languages.The API returns a list of known entities and general named entities (\"Person\", \"Location\", \"Organization\" etc) in a given document. Known entities are returned with Wikipedia Id and Wikipedia link, and also Bing Id which can be used in Bing Entity Search API. General named entities are returned with entity types. If a general named entity is also a known entity, then all information regarding it (Wikipedia Id, Bing Id, entity type etc) will be returned. See the <a href=\"https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/how-tos/text-analytics-how-to-entity-linking#supported-types-for-named-entity-recognition\">Supported Entity Types in Text Analytics API</a> for the list of supported Entity Types. See the <a href=\"https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/text-analytics-supported-languages\">Supported languages in Text Analytics API</a> for the list of enabled languages.",
        "operationId": "Entities",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "input",
            "in": "body",
            "description": "Collection of documents to analyze.",
            "required": true,
            "schema": {
              "$ref": "#/definitions/MultiLanguageBatchInput"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A successful call results in a list of recognized entities returned for each valid document",
            "schema": {
              "$ref": "#/definitions/EntitiesBatchResultV2dot1"
            }
          },
          "default": {
            "description": "Error Response",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        },
        "x-ms-examples": {
          "Successful Entities request": {
            "$ref": "./examples//SuccessfulEntitiesRequest.json"
          }
        },
        "deprecated": false
      }
    }
  },
  "definitions": {
    "MultiLanguageBatchInput": {
      "type": "object",
      "properties": {
        "documents": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/MultiLanguageInput"
          }
        }
      },
      "example": {
        "documents": [
          {
            "language": "en",
            "id": "1",
            "text": "Hello world. This is some input text that I love."
          },
          {
            "language": "fr",
            "id": "2",
            "text": "Bonjour tout le monde"
          },
          {
            "language": "es",
            "id": "3",
            "text": "La carretera estaba atascada. Había mucho tráfico el día de ayer."
          }
        ]
      }
    },
    "MultiLanguageInput": {
      "type": "object",
      "properties": {
        "language": {
          "description": "This is the 2 letter ISO 639-1 representation of a language. For example, use \"en\" for English; \"es\" for Spanish etc.,",
          "type": "string"
        },
        "id": {
          "description": "Unique, non-empty document identifier.",
          "type": "string"
        },
        "text": {
          "type": "string"
        }
      }
    },
    "Object": {
      "type": "object",
      "properties": {}
    },
    "KeyPhraseBatchResult": {
      "type": "object",
      "properties": {
        "documents": {
          "type": "array",
          "readOnly": true,
          "items": {
            "$ref": "#/definitions/KeyPhraseBatchResultItem"
          }
        },
        "errors": {
          "type": "array",
          "readOnly": true,
          "items": {
            "$ref": "#/definitions/ErrorRecord"
          }
        }
      }
    },
    "KeyPhraseBatchResultItem": {
      "type": "object",
      "properties": {
        "keyPhrases": {
          "description": "A list of representative words or phrases. The number of key phrases returned is proportional to the number of words in the input document.",
          "type": "array",
          "readOnly": true,
          "items": {
            "type": "string"
          }
        },
        "id": {
          "description": "Unique document identifier.",
          "type": "string",
          "readOnly": true
        }
      }
    },
    "ErrorRecord": {
      "type": "object",
      "properties": {
        "id": {
          "description": "Input document unique identifier the error refers to.",
          "type": "string"
        },
        "message": {
          "description": "Error message.",
          "type": "string"
        }
      }
    },
    "ErrorResponse": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "target": {
          "type": "string"
        },
        "innerError": {
          "$ref": "#/definitions/InternalError"
        }
      }
    },
    "InternalError": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "innerError": {
          "$ref": "#/definitions/InternalError"
        }
      }
    },
    "BatchInput": {
      "type": "object",
      "properties": {
        "documents": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Input"
          }
        }
      },
      "example": {
        "documents": [
          {
            "id": "1",
            "text": "Hello world"
          },
          {
            "id": "2",
            "text": "Bonjour tout le monde"
          },
          {
            "id": "3",
            "text": "La carretera estaba atascada. Había mucho tráfico el día de ayer."
          },
          {
            "id": "4",
            "text": ":) :( :D"
          }
        ]
      }
    },
    "Input": {
      "type": "object",
      "properties": {
        "id": {
          "description": "Unique, non-empty document identifier.",
          "type": "string"
        },
        "text": {
          "type": "string"
        }
      }
    },
    "LanguageBatchResult": {
      "type": "object",
      "properties": {
        "documents": {
          "type": "array",
          "readOnly": true,
          "items": {
            "$ref": "#/definitions/LanguageBatchResultItem"
          }
        },
        "errors": {
          "type": "array",
          "readOnly": true,
          "items": {
            "$ref": "#/definitions/ErrorRecord"
          }
        }
      }
    },
    "LanguageBatchResultItem": {
      "type": "object",
      "properties": {
        "id": {
          "description": "Unique document identifier.",
          "readOnly": true,
          "type": "string"
        },
        "detectedLanguages": {
          "description": "A list of extracted languages.",
          "type": "array",
          "readOnly": true,
          "items": {
            "$ref": "#/definitions/DetectedLanguage"
          }
        }
      }
    },
    "DetectedLanguage": {
      "type": "object",
      "properties": {
        "name": {
          "description": "Long name of a detected language (e.g. English, French).",
          "type": "string"
        },
        "iso6391Name": {
          "description": "A two letter representation of the detected language according to the ISO 639-1 standard (e.g. en, fr).",
          "type": "string"
        },
        "score": {
          "format": "double",
          "description": "A confidence score between 0 and 1. Scores close to 1 indicate 100% certainty that the identified language is true.",
          "type": "number"
        }
      }
    },
    "SentimentBatchResult": {
      "type": "object",
      "properties": {
        "documents": {
          "type": "array",
          "readOnly": true,
          "items": {
            "$ref": "#/definitions/SentimentBatchResultItem"
          }
        },
        "errors": {
          "type": "array",
          "readOnly": true,
          "items": {
            "$ref": "#/definitions/ErrorRecord"
          }
        }
      }
    },
    "SentimentBatchResultItem": {
      "type": "object",
      "properties": {
        "score": {
          "format": "double",
          "description": "A decimal number between 0 and 1 denoting the sentiment of the document. A score above 0.7 usually refers to a positive document while a score below 0.3 normally has a negative connotation. Mid values refer to neutral text.",
          "type": "number",
          "readOnly": true
        },
        "id": {
          "description": "Unique document identifier.",
          "readOnly": true,
          "type": "string"
        }
      }
    },
    "EntitiesBatchResultV2dot1": {
      "type": "object",
      "properties": {
        "documents": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/EntitiesBatchResultItemV2dot1"
          },
          "readOnly": true
        },
        "errors": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ErrorRecord"
          },
          "readOnly": true
        }
      }
    },
    "EntitiesBatchResultItemV2dot1": {
      "type": "object",
      "properties": {
        "id": {
          "description": "Unique document identifier.",
          "type": "string",
          "readOnly": true
        },
        "entities": {
          "description": "Recognized entities in the document.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/EntityRecordV2dot1"
          },
          "readOnly": true
        }
      }
    },
    "EntityRecordV2dot1": {
      "type": "object",
      "properties": {
        "name": {
          "description": "Entity formal name.",
          "type": "string"
        },
        "matches": {
          "description": "List of instances this entity appears in the text.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/MatchRecordV2dot1"
          }
        },
        "wikipediaLanguage": {
          "description": "Wikipedia language for which the WikipediaId and WikipediaUrl refers to.",
          "type": "string"
        },
        "wikipediaId": {
          "description": "Wikipedia unique identifier of the recognized entity.",
          "type": "string"
        },
        "wikipediaUrl": {
          "description": "URL for the entity's English Wikipedia page.",
          "type": "string",
          "readOnly": true
        },
        "bingId": {
          "description": "Bing unique identifier of the recognized entity. Use in conjunction with the Bing Entity Search API to fetch additional relevant information.",
          "type": "string"
        },
        "type": {
          "description": "Entity type from Named Entity Recognition model",
          "type": "string"
        },
        "subType": {
          "description": "Entity sub type from Named Entity Recognition model",
          "type": "string"
        }
      }
    },
    "MatchRecordV2dot1": {
      "type": "object",
      "properties": {
        "text": {
          "description": "Entity text as appears in the request.",
          "type": "string"
        },
        "offset": {
          "format": "int32",
          "description": "Start position (in Unicode characters) for the entity match text.",
          "type": "integer"
        },
        "length": {
          "format": "int32",
          "description": "Length (in Unicode characters) for the entity match text.",
          "type": "integer"
        }
      }
    }
  },
  "parameters": {
    "Endpoint": {
      "name": "Endpoint",
      "description": "Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com).",
      "x-ms-parameter-location": "client",
      "required": true,
      "type": "string",
      "in": "path",
      "x-ms-skip-url-encoding": true
    }
  }
}