Name: Text Intelligence API
Brand: quickpod
SKU: api-quickpod-aiquick-text
Availability: InStock
Author: API Market

Anil Singh

# Text Intelligence API

## Overview

The Text Intelligence API is a comprehensive suite of Natural Language Processing (NLP) tools designed to analyze and extract insights from text data. This powerful aggregate API offers a range of capabilities including sentiment analysis, toxicity detection, language identification, named entity recognition (NER), semantic similarity comparison, text ranking, and spellchecking. It's built for developers and AI engineers who need to quickly integrate advanced text processing into their applications.

Most input texts are limited to 512 characters, making the API ideal for processing short messages, comments, social media snippets, user-generated content, or brief document excerpts. Whether you're routing support tickets, moderating user content, enhancing search functionality, or enriching data for analytics, the Text Intelligence API provides accurate and efficient text understanding.

## Features

- **Sentiment Analysis:** Classify text as positive or negative with confidence scores, available for single texts or in batches.
- **Toxicity Detection:** Identify harmful or toxic content, providing a binary flag, label, and confidence score.
- **Language Detection:** Automatically determine the language of a text string (ISO 639-1 code) along with a probability breakdown for potential languages.
- **Named Entity Recognition (NER):** Extract key entities such as persons (PER), organizations (ORG), locations (LOC), and miscellaneous (MISC) with their character offsets.
- **Semantic Similarity:** Compute the cosine similarity score between two text strings using advanced sentence embeddings.
- **Text Ranking:** Rank a list of candidate texts by their semantic similarity to a given query, from most to least similar.
- **Spellcheck:** Detect and correct misspelled words in a text, providing the original, corrected, and a map of changes.

## Use Cases

The Text Intelligence API is versatile and can enhance a wide range of applications across various industries:

- **Customer Service & Support Automation:** Automatically route customer support tickets based on the detected language and sentiment (e.g., direct negative feedback to urgent queues, or Spanish-language queries to a specific team). Use toxicity detection to flag abusive messages.
- **Content Moderation & User-Generated Content (UGC) Management:** Monitor and filter online comments, forum posts, or social media content for toxicity, hate speech, or inappropriate language. Ensure quality control with automatic spellchecking before publication.
- **E-commerce Product Reviews & Feedback Analysis:** Analyze large volumes of product reviews to gauge overall sentiment, identify common issues (using NER to find product features mentioned negatively), and detect trends, helping businesses make informed decisions.
- **Search & Recommendation Engines:** Improve search relevance by leveraging semantic similarity to match user queries with documents, products, or articles that are conceptually related, even if they don't share exact keywords. Rank search results based on contextual relevance.
- **Data Preprocessing for Machine Learning:** Prepare raw text data for further analysis or machine learning tasks by identifying languages, extracting entities, or standardizing text through spell correction. This enhances the quality and interpretability of downstream models.

## Pricing

Pricing is based on API calls. Different pricing tiers are available based on usage volume.

## API Documentation

### Base URL

All API requests should be made to: `https://prod.api.market/api/v1/quickpod/aiquick-text`

### Authentication

Authentication is handled via API key. Include your API key in the request header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Endpoints

#### Health Check

`GET /health`
Service health check to ensure the API is operational.

```bash
curl -X GET "https://prod.api.market/api/v1/quickpod/aiquick-text/health" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Response (200 OK):**
```json
{
  "ok": true,
  "service": "Text Intelligence API"
}
```

---

#### Sentiment Analysis

`POST /v1/sentiment`
Classify a single text as positive or negative with a confidence score.

**Request Body Example:**
```json
{
  "text": "This product is absolutely fantastic!"
}
```

```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquick-text/v1/sentiment" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "text": "This product is absolutely fantastic!"
  }'
```

**Response (200 OK):**
```json
{
  "text": "This product is absolutely fantastic!",
  "label": "positive",
  "score": 0.9998
}
```

---

#### Batch Sentiment Analysis

`POST /v1/sentiment/batch`
Classify multiple texts in a single request, returning a label and score for each item.

**Request Body Example:**
```json
{
  "texts": [
    "Great product!",
    "Awful service."
  ]
}
```

```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquick-text/v1/sentiment/batch" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "texts": [
      "Great product!",
      "Awful service."
    ]
  }'
```

**Response (200 OK):**
```json
{
  "results": [
    {
      "label": "positive",
      "score": 0.9998
    },
    {
      "label": "negative",
      "score": 0.9987
    }
  ]
}
```

---

#### Toxicity Detection

`POST /v1/toxicity`
Detect whether a text contains toxic or harmful content.

**Request Body Example:**
```json
{
  "text": "I hate you and want you gone."
}
```

```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquick-text/v1/toxicity" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "text": "I hate you and want you gone."
  }'
```

**Response (200 OK):**
```json
{
  "text": "I hate you.",
  "toxic": true,
  "label": "toxic",
  "score": 0.9871
}
```

---

#### Language Detection

`POST /v1/language/detect`
Identify the language of a text with a per-language probability breakdown.

**Request Body Example:**
```json
{
  "text": "The quick brown fox jumps over the lazy dog."
}
```

```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquick-text/v1/language/detect" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "text": "The quick brown fox jumps over the lazy dog."
  }'
```

**Response (200 OK):**
```json
{
  "detected": "en",
  "probabilities": [
    {
      "lang": "en",
      "prob": 0.9999
    }
  ]
}
```

**Error Response (422 Unprocessable Entity):**
Occurs if the text is too short or ambiguous to detect a language.

---

#### Named Entity Recognition (NER)

`POST /v1/ner`
Extract named entities — persons, locations, organisations, and miscellaneous — with character offsets.

**Request Body Example:**
```json
{
  "text": "Apple Inc. was founded by Steve Jobs in Cupertino, California."
}
```

```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquick-text/v1/ner" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "text": "Apple Inc. was founded by Steve Jobs in Cupertino, California."
  }'
```

**Response (200 OK):**
```json
{
  "text": "Apple Inc. was founded by Steve Jobs in Cupertino, California.",
  "entities": [
    {
      "word": "Apple Inc.",
      "type": "ORG",
      "score": 0.9994,
      "start": 0,
      "end": 10
    },
    {
      "word": "Steve Jobs",
      "type": "PER",
      "score": 0.9998,
      "start": 26,
      "end": 36
    },
    {
      "word": "Cupertino",
      "type": "LOC",
      "score": 0.9991,
      "start": 40,
      "end": 49
    }
  ]
}
```

---

#### Semantic Similarity

`POST /v1/similarity`
Compute the cosine similarity score between two texts using sentence embeddings.

**Request Body Example:**
```json
{
  "text1": "The cat sat on the mat.",
  "text2": "A feline rested on a rug."
}
```

```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquick-text/v1/similarity" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "text1": "The cat sat on the mat.",
    "text2": "A feline rested on a rug."
  }'
```

**Response (200 OK):**
```json
{
  "text1": "The cat sat on the mat.",
  "text2": "A feline rested on a rug.",
  "similarity": 0.7842
}
```

---

#### Similarity Ranking

`POST /v1/similarity/rank`
Rank candidate texts by semantic similarity to a query, highest first.

**Request Body Example:**
```json
{
  "query": "machine learning frameworks",
  "candidates": [
    "PyTorch for deep learning",
    "Best restaurants in Paris",
    "TensorFlow tutorial",
    "Cooking pasta at home"
  ]
}
```

```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquick-text/v1/similarity/rank" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "query": "machine learning frameworks",
    "candidates": [
      "PyTorch for deep learning",
      "Best restaurants in Paris",
      "TensorFlow tutorial",
      "Cooking pasta at home"
    ]
  }'
```

**Response (200 OK):**
```json
{
  "query": "machine learning frameworks",
  "ranked": [
    {
      "text": "PyTorch for deep learning",
      "score": 0.8241
    },
    {
      "text": "TensorFlow tutorial",
      "score": 0.7893
    },
    {
      "text": "Best restaurants in Paris",
      "score": 0.0912
    }
  ]
}
```

---

#### Spellcheck

`POST /v1/spellcheck`
Detect misspelled words and return a corrected version of the text.

**Request Body Example:**
```json
{
  "text": "Ths is a smple test sentance."
}
```

```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquick-text/v1/spellcheck" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "text": "Ths is a smple test sentance."
  }'
```

**Response (200 OK):**
```json
{
  "original": "Ths is a smple test sentance.",
  "corrected": "The is a simple test sentence.",
  "misspelled": {
    "Ths": "The",
    "smple": "simple",
    "sentance": "sentence"
  }
}
```

## Status Codes

- **200 OK:** The request was successful, and the response body contains the requested data or the result of the operation.
- **201 Created:** (Not typically used by this API, but common for resource creation).
- **400 Bad Request:** The request was malformed or contained invalid parameters. Check your request body and query parameters for correctness.
- **401 Unauthorized:** Your API key is missing or invalid. Ensure `x-api-market-key` header is present and contains a valid key.
- **403 Forbidden:** Your API key is valid, but you do not have sufficient permissions to access the requested resource or perform the operation.
- **404 Not Found:** The requested endpoint or resource does not exist. Verify the URL path.
- **422 Unprocessable Entity:** The request was well-formed but could not be processed due to semantic errors, such as text being too short for language detection. The response body may contain more details.
- **429 Too Many Requests:** You have exceeded the API's rate limits. Slow down your requests and implement a retry strategy with exponential backoff.
- **500 Internal Server Error:** An unexpected error occurred on the server. This is typically a temporary issue; retrying the request after a short delay might resolve it.
- **503 Service Unavailable:** The service is temporarily unable to handle the request, often due to maintenance or overload. Retry the request after a short interval.

## Rate Limits

The Text Intelligence API has rate limits in place to ensure fair usage and service stability. If you exceed the allocated number of requests within a given time frame, you will receive a `429 Too Many Requests` HTTP status code. To avoid hitting rate limits, distribute your requests over time and implement retry logic with exponential backoff for `429` and `503` responses. Contact support if you require higher rate limits for your application.

## Error Handling

Effective error handling is crucial for building robust applications. The Text Intelligence API communicates errors using standard HTTP status codes and provides additional details in the JSON response body where applicable.

- **Interpreting Error Responses:** Always check the HTTP status code first. For `4xx` and `5xx` errors, the response body will typically contain a JSON object with an `error` field that provides a `code`, `message`, and `status` to help diagnose the issue.

    ```json
    {
      "error": {
        "code": "validation_error",
        "message": "Input text cannot be empty.",
        "status": 400
      }
    }
    ```
    ```json
    {
      "error": {
        "code": "text_too_short",
        "message": "Text is too short or ambiguous for language detection.",
        "status": 422
      }
    }
    ```

- **Common Errors and Resolution:**
  - **400 Bad Request:** This means an issue with your request payload. Review the endpoint's request body schema and examples to ensure your data is correctly formatted and all required fields are present.
    - **401 Unauthorized:** Your API key is incorrect or missing. Double-check that `x-api-market-key` is set correctly in your request headers.
    - **429 Too Many Requests:** You've hit a rate limit. Implement a delay and retry mechanism, preferably with exponential backoff.
    - **500/503 Server Errors:** These are server-side issues. While rare, they can occur. Implement retries with a short delay for these errors.

- **Recommended Retry Strategies:** For transient errors like `429 Too Many Requests`, `500 Internal Server Error`, and `503 Service Unavailable`, implement an exponential backoff strategy. This involves retrying the request after increasing delays (e.g., 1s, 2s, 4s, 8s) up to a maximum number of retries or a total timeout. This prevents overwhelming the API during temporary issues.

## FAQ

**What is the maximum text length supported?**

Most endpoints support an input text length of up to 512 characters. Texts longer than this limit will typically be truncated.

**Which languages does the API support for language detection?**

The Language Detection endpoint can identify a broad range of languages and returns ISO 639-1 codes. The `probabilities` field in the response provides a breakdown of candidate languages.

**Can I process multiple texts in a single request?**

Yes, the `/v1/sentiment/batch` endpoint specifically allows you to process multiple texts for sentiment analysis in one API call.

**How accurate are the models used in the API?**

The API utilizes well-regarded open-source models (e.g., `distilbert-base-uncased-finetuned-sst-2-english` for sentiment, `unitary/toxic-bert` for toxicity, `dslim/bert-base-NER` for NER, `sentence-transformers/all-MiniLM-L6-v2` for similarity, `langdetect` for language detection, `pyspellchecker` for spellcheck). While highly accurate, performance can vary depending on the specific text and domain.

**What should I do if I get a 429 Too Many Requests error?**

This means you've hit your rate limit. Implement a retry strategy with exponential backoff (waiting longer between retries) to avoid overwhelming the API. If you consistently need higher limits, please contact support.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.

Sentiment and toxicity scoring, language detection, named entity recognition, semantic similarity and spellcheck, with batch support, in one NLP API.

Text Intelligence API