Name: Score Text API: Analyze Text Readability & Engagement
Brand: skycraft
SKU: api-skycraft-score-text
Availability: InStock
Author: API Market

Pulkit


# score-text

## Overview

The `score-text` API provides a comprehensive analysis of text, evaluating its readability, skimmability, interestingness, and style. It returns detailed metrics, including readability scores (Flesch, SMOG, ARI, etc.), skimmability components (bullet points, images, headings), and assessments of interestingness and style.  This API enables developers to quickly assess the quality and effectiveness of written content.

## Features

*   **Readability Scoring:** Evaluates text readability using multiple industry-standard scoring methods.
*   **Skimmability Analysis:**  Identifies elements that contribute to how easily a text can be skimmed.
*   **Interestingness Assessment:** Gauges factors contributing to how engaging a text is.
*   **Style Evaluation:**  Analyzes writing style, grammar, and spelling.
*   **Word and Sentence Count:** Provides basic text statistics.
*   **Estimated Reading Time:** Calculates an approximate reading time in seconds.

## Use Cases

*   **Educational Content Optimization:** Educators can use the API to ensure learning materials are appropriately tailored to students' reading levels. For example, simplifying the language in a textbook chapter to improve student comprehension.
*   **Marketing Copy Analysis:**  Marketing teams can assess the readability and interestingness of ad copy, blog posts, and website content to maximize audience engagement and conversion rates. Optimizing a sales email with improved skimmability scores will ensure important information is communicated effectively.
*   **Content Management System (CMS) Integration:** Developers can integrate the API into a CMS to automatically score content as it's being created, providing real-time feedback to writers and editors.
*   **SEO Optimization:** Analyze website content to improve readability and skimmability for search engines, leading to better rankings. Analyze content readability for targeted audiences, such as increasing readability to get featured snippets in search results.
*   **Technical Documentation Review:** Ensure technical documentation is clear, concise, and easy to understand for developers and end-users.


## API Documentation

### Base URL

All API requests should be made to: `https://prod.api.market/api/v1/magicapi/score-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

#### GET /score-text

This endpoint analyzes the provided text and returns a comprehensive score for readability, skimmability, interestingness, and style.

**Request Parameters:**

*   `title` (string, required): The title of the text to score (maximum length: 10000 characters). Example: "A short story"
*   `text` (string, required): The text to score for multiple metrics (maximum length: 10000 characters). Example: "A nice short story to be analyzed"

**Request Headers:**

*   `x-api-market-key` (string, required): Your API.market API key

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/score-text/score-text?title=A%20short%20story&text=A%20nice%20short%20story%20to%20be%20analyzed" \
-H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response (200 OK):**

```json
{
  "number_of_words": 7,
  "number_of_sentences": 1,
  "readability": {
    "mainscores": {
      "total_possible": 10,
      "total": 10
    },
    "subscores": {
      "reading_time_seconds": 1,
      "forcast": -0.99,
      "flesch": 78.873,
      "smog": 8.842,
      "ari": 0.237,
      "lix": -0.99,
      "coleman_liau": 2.633,
      "kincaid": 3.997,
      "fog": 8.514
    }
  },
  "skimmability": {
    "mainscores": {
      "total_possible": 10,
      "total": 3.076923
    },
    "subscores": {
      "bullet_point_ratio_score": [
        0,
        2
      ],
      "image_score": [
        0,
        3
      ],
      "highlighted_word_ratio_score": [
        0,
        2
      ],
      "video_score": [
        0,
        1
      ],
      "paragraph_score": [
        4,
        3
      ],
      "paragraph_headline_ratio_score": [
        0,
        2
      ]
    }
  },
  "interestingness": {
    "mainscores": {
      "total_possible": 10,
      "total": 3.571429
    },
    "subscores": {
      "title_rating_score": [
        1,
        4
      ],
      "quote_score": [
        0,
        1
      ],
      "length_score": [
        0,
        2
      ],
      "link_score": [
        0,
        2
      ],
      "google_hits_score": [
        4,
        4
      ]
    }
  },
  "style": {
    "mainscores": {
      "total_possible": 10,
      "total": 10
    },
    "subscores": {
      "abbreviation_score": [
        3,
        3
      ],
      "style_score": [
        5,
        5
      ],
      "spelling_score": [
        5,
        5
      ]
    }
  },
  "total_score": 6.662088
}
```

## Status Codes

*   200 OK: Request successful.  The analysis results are returned in the response body.
*   401 Unauthorized: Missing or invalid API key. Ensure the `x-api-market-key` header is included and contains a valid key.
*   402 Payment Required: Your account does not have sufficient funds.
*   403 Forbidden: Valid API key but insufficient permissions to access the requested resource.
*   404 Not Found: The requested resource was not found (e.g., incorrect URL).
*   406 Not Acceptable: The server cannot produce a response matching the client's Accept headers.
*   429 Too Many Requests: Rate limit exceeded.  See the Rate Limits section for details.

## Rate Limits

Specific rate limits will depend on your subscription plan. If you exceed the rate limit, the API will return a 429 Too Many Requests error.  Implement error handling and retry logic with exponential backoff to handle rate limiting gracefully.

## Error Handling

The API returns error responses in JSON format.  The error object typically includes a `code`, `message`, and `status` field.

**Example Error Response:**

```json
{
  "error": {
    "code": "missing_parameter",
    "message": "The 'text' parameter is required.",
    "status": 400
  }
}
```

**Common Errors and Solutions:**

*   `missing_parameter`: A required parameter is missing from the request. Check the request parameters and ensure all required parameters are present.
*   `invalid_parameter`: A parameter value is invalid. Check the parameter values against the API documentation and ensure they are valid.
*   `unauthorized`: Invalid API key.  Double-check your API key and ensure it's included in the `x-api-market-key` header.
*   `rate_limit_exceeded`: You have exceeded the rate limit.  Implement retry logic with exponential backoff.
*   `internal_server_error`: An unexpected error occurred on the server.  Retry the request after a short delay.  If the error persists, contact support.

## Implementation Guide

This section provides a detailed guide on how to implement and use the `score-text` API.

### Example Code

#### JavaScript

```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/score-text";

async function scoreText(title, text) {
  try {
    const url = `${baseUrl}/score-text?title=${encodeURIComponent(title)}&text=${encodeURIComponent(text)}`;
    const response = await fetch(url, {
      method: "GET",
      headers: {
        "x-api-market-key": apiKey
      }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const data = await response.json();
    return data;
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

// Example usage
async function main() {
  const title = "My Article Title";
  const text = "This is the text of my article.";
  try {
    const result = await scoreText(title, text);
    console.log("Text Score:", result);
  } catch (error) {
    console.error("Failed to score text:", error);
  }
}

main();
```

#### Python

```python
import requests
import urllib.parse

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/score-text"

def score_text(title, text):
    """
    Scores the readability, skimmability, interestingness, and style of a text.
    """
    try:
        url = f"{BASE_URL}/score-text?title={urllib.parse.quote(title)}&text={urllib.parse.quote(text)}"
        headers = {"x-api-market-key": API_KEY}
        response = requests.get(url, headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} - {response.text}")

        return response.json()

    except Exception as e:
        print(f"Error: {e}")
        raise

# Example usage
if __name__ == "__main__":
    title = "My Article Title"
    text = "This is the text of my article."
    try:
        result = score_text(title, text)
        print("Text Score:", result)
    except Exception as e:
        print("Failed to score text.")
```

#### cURL

```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/score-text/score-text?title=My%20Article%20Title&text=This%20is%20the%20text%20of%20my%20article." \
-H "x-api-market-key: YOUR_API_MARKET_KEY"
```

### Performance Optimization

*   **Cache Results:**  If you are analyzing the same text multiple times, cache the results to avoid unnecessary API calls.
*   **Monitor Usage:** Track your API usage to identify potential areas for optimization.

## FAQ

*   **What does the `total_score` represent?**
    *   The `total_score` is a combined metric reflecting the overall quality and effectiveness of the text based on readability, skimmability, interestingness, and style. It is a weighted average.

*   **How are the readability subscores calculated?**
    *   The readability subscores (Flesch, SMOG, ARI, etc.) are calculated using established formulas that take into account factors such as sentence length and word complexity.

*   **What does a low skimmability score indicate?**
    *   A low skimmability score suggests that the text may be difficult to skim quickly due to a lack of visual cues such as bullet points, headings, and images.

*   **How can I improve the interestingness score of my text?**
    *   You can improve the interestingness score by incorporating elements such as quotes, links, and engaging titles. Length can hurt, but that is not always true. Researching proper google hits is helpful.

## 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@api.market.
```

Analyze text readability, skimmability, style, and interestingness with our API. Optimize content for engagement and comprehension.

Score Text API: Analyze Text Readability & Engagement

FREE