Name: Sentiment Analysis API: Get Positive, Negative, Neutral Scor
Brand: viv-data
SKU: api-viv-data-sentiment
Availability: InStock
Author: API Market

gia ly bui

# Sentiment Analysis — Positive, Negative, Neutral

## Overview

The Sentiment Analysis API provides a powerful and easy-to-use tool for evaluating the emotional tone of any given text. Leveraging the VADER (Valence Aware Dictionary and sEntiment Reasoner) model, this API delivers a nuanced sentiment breakdown, including a compound score, and probabilities for positive, negative, and neutral sentiment. It then categorizes the overall sentiment as "positive," "negative," or "neutral" based on the compound score.

Optimized specifically for social media and short texts, this API is ideal for a wide range of applications, from analyzing customer reviews to monitoring brand perception on social platforms. It operates as an offline model, ensuring rapid processing without the need for complex API keys for the underlying VADER model.

## Features

*   **Real-time Sentiment Analysis:** Get instant sentiment insights for any text input.
*   **Comprehensive Scoring:** Returns a compound score, along with positive, negative, and neutral probability scores.
*   **Intuitive Sentiment Labels:** Categorizes text into "positive," "negative," or "neutral" for easy interpretation.
*   **VADER Model:** Utilizes VADER, a lexicon and rule-based sentiment analysis tool specifically tuned to sentiments expressed in social media.
*   **Single Endpoint Integration:** Analyze sentiment with a straightforward GET request.
*   **Free Tier Available:** Start analyzing text with a generous free usage tier.

## Use Cases

The Sentiment Analysis API is versatile and can be applied across various industries to extract valuable insights from textual data:

*   **Customer Feedback Analysis:** Automatically process and categorize customer reviews, support tickets, and survey responses to gauge satisfaction levels and identify areas for product or service improvement in e-commerce, SaaS, and hospitality sectors.
*   **Social Media Monitoring:** Track real-time public opinion and brand perception by analyzing comments, posts, and mentions across platforms like X (Twitter), Facebook, and Reddit, crucial for marketing and public relations teams.
*   **Market Research & Competitive Intelligence:** Gain insights into market trends, consumer preferences, and sentiment towards competitors by analyzing product reviews, news articles, and forum discussions.
*   **Content Moderation:** Automatically flag and prioritize user-generated content on online forums, community platforms, or dating apps that exhibits strong negative or aggressive sentiment, aiding in maintaining a healthy online environment.
*   **Employee Experience (EX) Insights:** Analyze internal communications, employee survey responses, and feedback platforms to understand employee morale, identify pain points, and foster a more positive workplace culture.

## Pricing

The Sentiment Analysis API operates on a usage-based pricing model.

*   1 API unit equals 1 text analysis request.

Different pricing tiers are available based on your usage volume:

*   **Free Tier:** 2,000 requests per month
*   **Pro Tier:** $19.99 for 20,000 requests per month

## API Documentation

### Base URL

All API requests should be made to the following base URL:

`https://prod.api.market/api/v1/viv-data/sentiment`

### Authentication

Authentication is handled via an API key. Include your API key in the `x-api-market-key` request header for all API calls:

```
x-api-market-key: YOUR_API_MARKET_KEY
```

Replace `YOUR_API_MARKET_KEY` with your actual API.market key.


### Endpoints

#### 1. Analyze Sentiment

Analyzes the sentiment of a given text string.

*   **Path:** `/analyze`
*   **Method:** `GET`
*   **Summary:** Analyze the sentiment of a given text.
*   **Description:** This endpoint accepts a text string as a query parameter and returns a detailed sentiment breakdown, including compound, positive, negative, and neutral scores, along with an overall sentiment label.

**Parameters:**

| Name | Type   | In    | Required | Description         | Schema Type |
| :--- | :----- | :---- | :------- | :------------------ | :---------- |
| text | string | query | True     | The text to analyze. | `string`    |

**Request Example (cURL):**

```bash
curl -X GET "https://prod.api.market/api/v1/viv-data/sentiment/analyze?text=This%20product%20is%20amazing!" -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Response Example (200 OK):**

```json
{
  "text": "This product is amazing!",
  "sentiment": "positive",
  "compound": 0.82,
  "positive": 0.75,
  "negative": 0.0,
  "neutral": 0.25
}
```

**Response Schema (`SentimentResult`):**

| Property  | Type    | Description                                                 |
| :-------- | :------ | :---------------------------------------------------------- |
| `text`    | string  | The original text that was analyzed.                        |
| `sentiment` | string  | The overall sentiment label: "positive", "negative", or "neutral". |
| `compound` | number  | The normalized, weighted composite score, ranging from -1 (most extreme negative) to +1 (most extreme positive). |
| `positive` | number  | The probability of the text expressing positive sentiment (0 to 1). |
| `negative` | number  | The probability of the text expressing negative sentiment (0 to 1). |
| `neutral`  | number  | The probability of the text expressing neutral sentiment (0 to 1). |

**Error Response (422 Unprocessable Entity - Validation Error):**

This error occurs if a required parameter, such as `text`, is missing or invalid.

```json
{
  "detail": [
    {
      "loc": [
        "query",
        "text"
      ],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

#### 2. Health Check

Checks the health status of the API.

*   **Path:** `/health`
*   **Method:** `GET` or `HEAD`
*   **Summary:** Health check for the API.
*   **Description:** This endpoint can be used to monitor the API's availability and responsiveness. A `200 OK` response indicates that the service is operational.

**Parameters:** None (other than `x-api-market-key` header).

**Request Example (cURL):**

```bash
curl -X GET "https://prod.api.market/api/v1/viv-data/sentiment/health" -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Response Example (200 OK):**

```json
{}
```

#### 3. Root Endpoint

A basic endpoint to confirm connectivity to the API.

*   **Path:** `/`
*   **Method:** `GET`
*   **Summary:** Root endpoint.
*   **Description:** A simple endpoint that responds if the API is reachable.

**Parameters:** None (other than `x-api-market-key` header).

**Request Example (cURL):**

```bash
curl -X GET "https://prod.api.market/api/v1/viv-data/sentiment/" -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Response Example (200 OK):**

```json
{}
```

## Status Codes

Understanding the HTTP status codes returned by the API is crucial for effective error handling:

*   **`200 OK`**: The request was successful, and the API has returned the expected data.
*   **`201 Created`**: (Not typically used by this API, but common for resource creation). The request has been fulfilled, resulting in the creation of a new resource.
*   **`400 Bad Request`**: The request could not be understood or was missing required parameters due to invalid input. For example, a malformed JSON payload.
*   **`401 Unauthorized`**: The request requires user authentication. This usually means the `x-api-market-key` header is missing or contains an invalid API key.
*   **`403 Forbidden`**: The server understood the request but refuses to authorize it. This may occur if your API key has insufficient permissions for the requested action.
*   **`404 Not Found`**: The requested resource could not be found. This typically indicates an incorrect endpoint path.
*   **`422 Unprocessable Entity`**: The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions. This often occurs due to validation errors (e.g., missing a required query parameter like `text`).
*   **`429 Too Many Requests`**: You have sent too many requests in a given amount of time ("rate limiting"). You should wait before making further requests.
*   **`500 Internal Server Error`**: A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
*   **`503 Service Unavailable`**: The server is currently unable to handle the request due to temporary overload or scheduled maintenance. This is usually a temporary condition.

## Implementation Guide

This section provides code samples to help you quickly integrate the Sentiment Analysis API into your applications. As this is a synchronous API, examples focus on making a single request and directly processing the response.

### Example Code

#### JavaScript

```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/viv-data/sentiment";

async function analyzeSentiment(text) {
  try {
    const encodedText = encodeURIComponent(text);
    const response = await fetch(`${baseUrl}/analyze?text=${encodedText}`, {
      method: "GET",
      headers: {
        "x-api-market-key": apiKey,
        "Content-Type": "application/json"
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`API error: ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
    }

    const sentimentResult = await response.json();
    console.log("Sentiment Analysis Result:", sentimentResult);
    return sentimentResult;

  } catch (error) {
    console.error("Error analyzing sentiment:", error);
    throw error;
  }
}

// Example usage:
analyzeSentiment("This product is absolutely fantastic and works perfectly!")
  .then(result => console.log("Overall sentiment:", result.sentiment))
  .catch(error => console.error("Failed to analyze:", error));

analyzeSentiment("I'm quite indifferent about this service. It's just okay.")
  .then(result => console.log("Overall sentiment:", result.sentiment))
  .catch(error => console.error("Failed to analyze:", error));

analyzeSentiment("The worst customer service I have ever experienced. Absolutely terrible.")
  .then(result => console.log("Overall sentiment:", result.sentiment))
  .catch(error => console.error("Failed to analyze:", error));
```

#### Python

```python
import requests
import json

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/viv-data/sentiment"

def analyze_sentiment(text):
    headers = {
        "x-api-market-key": API_KEY,
        "Content-Type": "application/json"
    }
    params = {
        "text": text
    }

    try:
        response = requests.get(f"{BASE_URL}/analyze", headers=headers, params=params)
        response.raise_for_status()  # Raises HTTPError for bad responses (4xx or 5xx)

        sentiment_result = response.json()
        print("Sentiment Analysis Result:", json.dumps(sentiment_result, indent=2))
        return sentiment_result

    except requests.exceptions.HTTPError as http_err:
        print(f"HTTP error occurred: {http_err} - {response.text}")
        raise
    except requests.exceptions.ConnectionError as conn_err:
        print(f"Connection error occurred: {conn_err}")
        raise
    except requests.exceptions.Timeout as timeout_err:
        print(f"Timeout error occurred: {timeout_err}")
        raise
    except requests.exceptions.RequestException as req_err:
        print(f"An unexpected error occurred: {req_err}")
        raise

# Example usage:
try:
    print("\n--- Example 1: Positive Sentiment ---")
    result1 = analyze_sentiment("This product is absolutely fantastic and works perfectly!")
    print(f"Overall sentiment: {result1['sentiment']}")

    print("\n--- Example 2: Neutral Sentiment ---")
    result2 = analyze_sentiment("I'm quite indifferent about this service. It's just okay.")
    print(f"Overall sentiment: {result2['sentiment']}")

    print("\n--- Example 3: Negative Sentiment ---")
    result3 = analyze_sentiment("The worst customer service I have ever experienced. Absolutely terrible.")
    print(f"Overall sentiment: {result3['sentiment']}")
    
    # Example 4: Missing text parameter (will raise an error)
    # print("\n--- Example 4: Missing text parameter (expecting error) ---")
    # analyze_sentiment("")

except Exception as e:
    print(f"An error occurred during sentiment analysis: {e}")
```

#### cURL

```bash
# Example 1: Analyze a positive sentence
curl -X GET "https://prod.api.market/api/v1/viv-data/sentiment/analyze?text=This%20product%20is%20amazing!" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY" \
     -H "Content-Type: application/json"

# Example 2: Analyze a negative sentence
curl -X GET "https://prod.api.market/api/v1/viv-data/sentiment/analyze?text=I%20am%20very%20disappointed%20with%20the%20quality." \
     -H "x-api-market-key: YOUR_API_MARKET_KEY" \
     -H "Content-Type: application/json"

# Example 3: Analyze a neutral sentence
curl -X GET "https://prod.api.market/api/v1/viv-data/sentiment/analyze?text=The%20weather%20today%20is%20partly%20cloudy." \
     -H "x-api-market-key: YOUR_API_MARKET_KEY" \
     -H "Content-Type: application/json"

# Example 4: Health check
curl -X GET "https://prod.api.market/api/v1/viv-data/sentiment/health" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"

# Example 5: Root endpoint
curl -X GET "https://prod.api.market/api/v1/viv-data/sentiment/" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

## FAQ

### What is VADER and why is it used?

VADER (Valence Aware Dictionary and sEntiment Reasoner) is a lexicon- and rule-based sentiment analysis model designed specifically for text commonly found on social media. It performs well on short, informal content such as tweets, comments, and reviews, making it ideal for sentiment analysis in real-world applications.

---

### How are the sentiment scores calculated?

The API returns four sentiment scores:

- **Compound** – A normalized, weighted composite score ranging from **-1** (most negative) to **+1** (most positive).
- **Positive** – The proportion of positive sentiment in the text.
- **Negative** – The proportion of negative sentiment in the text.
- **Neutral** – The proportion of neutral sentiment in the text.

The **Positive**, **Negative**, and **Neutral** scores always add up to **1**.

The overall `sentiment` label is determined from the `compound` score:

- `compound > 0.05` → **Positive**
- `compound < -0.05` → **Negative**
- Otherwise → **Neutral**

---

### What kind of text works best with this API?

The API performs best on:

- Social media posts
- Comments
- Customer reviews
- Short messages
- Informal or conversational text

These are the types of content VADER was specifically designed to analyze.

---

### Is there a free trial or free tier available?

Yes. A free tier is available and includes **up to 2,000 requests per month**, making it suitable for testing and low-volume applications.

---

### How should I handle API errors?

Always check the HTTP status code returned by the API.

- **`2xx`** – Request completed successfully.
- **Non-`2xx`** – An error occurred.

When an error occurs, the response body typically includes a JSON object with a `detail` field describing the issue. For temporary failures such as **`429 Too Many Requests`** or **`5xx` server errors**, implement retry logic using exponential backoff.

## 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.

Analyze text sentiment using the VADER model. Obtain accurate positive, negative, neutral, and compound scores for reviews, social media, and customer feedback.

Sentiment Analysis API: Get Positive, Negative, Neutral Scor

Free

Viv Data

Accurately analyze emotional tone in any text using the VADER model, delivering compound, positive, negative, and neutral sentiment breakdowns, optimized for so