Name: Text to Slug API | Convert Text to URL Slugs, Unicode Safe
Brand: viv-data
SKU: api-viv-data-slug
Availability: InStock
Author: API Market

gia ly bui

# Text to Slug — URL-Friendly String Converter

## Overview
The Text to Slug API is a robust tool designed to convert any arbitrary text string into a clean, URL-friendly slug. It intelligently handles complex scenarios, including Unicode characters, diacritics, and special symbols, ensuring the resulting slug is always valid and highly readable for web use. This API is essential for applications requiring consistent and SEO-friendly URL generation, such as Content Management Systems (CMS), blog platforms, e-commerce sites, and document management systems.

**Key Capabilities:**
- Transforms "Hello World!" into `hello-world`
- Converts "Cómo estás?" into `como-estas`
- Processes "Café & Restaurant" into `cafe-restaurant`

## Features
*   **Unicode and Diacritic Handling:** Correctly processes text containing international characters and accented letters, converting them into their closest ASCII equivalents.
*   **Special Character Normalization:** Effectively removes or replaces special characters and symbols with URL-safe alternatives.
*   **Consistent Separator Replacement:** Uses a user-defined or default separator (e.g., hyphen `-` or underscore `_`) to join words.
*   **Multi-language Support:** Designed to work accurately across a wide range of languages.
*   **Pure Python Backend:** Offers efficient and instant response times.
*   **Easy Integration:** Simple API structure allows for quick and straightforward integration into any application.

## Use Cases
*   **Content Management Systems (CMS):** Automatically generate clean, readable URLs for blog posts, articles, and pages, improving SEO and user experience.
*   **E-commerce Platforms:** Create unique and descriptive product URLs that are easy for search engines to crawl and users to remember.
*   **Document & File Management:** Standardize filenames for uploaded documents or generated reports, ensuring compatibility across different systems.
*   **SEO Optimization:** Produce search engine-friendly URLs for any web content, contributing to higher search rankings and better visibility.
*   **Internal Knowledge Bases:** Transform titles of knowledge base articles or wiki pages into navigable, permanent links.
*   **Event and Directory Listings:** Generate clean slugs for event titles, business names, or directory entries for use in URLs.

## Pricing
Pricing for the Text to Slug API is based on usage volume. 1 API unit equals 1 slug generation request. Different pricing tiers are available based on your monthly usage volume:

*   **Free:** 2,000 requests per month
*   **Pro $19.99:** 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/slug`

### Authentication
Authentication is handled via an API key. You must include your API key in the `x-api-market-key` header for every request:

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

Replace `YOUR_API_MARKET_KEY` with your actual API key.


### Endpoints

#### 1. Generate Slug
Converts a given text string into a URL-friendly slug.

`GET /api/v1/viv-data/slug/slugify`

**Parameters:**

| Name      | Type     | Required | Description                                     | Default |
| :-------- | :------- | :------- | :---------------------------------------------- | :------ |
| `text`    | `string` | Yes      | The text string to convert to a slug.           | N/A     |
| `separator` | `string` | No       | The word separator to use in the slug.          | `-`     |

**Example Request:**
```bash
curl -X GET "https://prod.api.market/api/v1/viv-data/slug/slugify?text=Hello%20World!&separator=-" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response:**
```json
{
  "original": "Hello World!",
  "slug": "hello-world",
  "length": 11
}
```

**Example Request (with Unicode and custom separator):**
```bash
curl -X GET "https://prod.api.market/api/v1/viv-data/slug/slugify?text=Caf%C3%A9%20%26%20Restaurant&separator=_" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response:**
```json
{
  "original": "Café & Restaurant",
  "slug": "cafe_restaurant",
  "length": 15
}
```

#### 2. Health Check
Checks the health and availability of the API service.

`GET /api/v1/viv-data/slug/health`

**Parameters:**
None

**Example Request:**
```bash
curl -X GET "https://prod.api.market/api/v1/viv-data/slug/health" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response:**
```json
{}
```

## Status Codes
A comprehensive list of HTTP status codes you might encounter:

*   **200 OK**: Request successful. The response body contains the requested data (e.g., the generated slug).
*   **400 Bad Request**: The request was malformed or contained invalid input parameters. Check your `text` and `separator` query parameters.
*   **401 Unauthorized**: Missing or invalid API key. Ensure `x-api-market-key` header is present and contains a valid key.
*   **403 Forbidden**: Valid API key but insufficient permissions to access the resource.
*   **404 Not Found**: The requested resource or endpoint does not exist. Verify the endpoint path.
*   **422 Unprocessable Entity**: Validation error. The request entity was syntactically correct but semantically incorrect (e.g., missing a required parameter like `text`). The response will include details about the validation error.
*   **429 Too Many Requests**: Rate limit exceeded. You have sent too many requests in a given time frame. Refer to the Rate Limits section.
*   **500 Internal Server Error**: An unexpected error occurred on the server. This is a server-side issue, and you should contact support if it persists.
*   **503 Service Unavailable**: The service is temporarily unable to handle the request, usually due to maintenance or overload. Retry after a short delay.


## Implementation Guide

### Example Code

Here are code samples in JavaScript, Python, and cURL demonstrating how to use the Text to Slug API synchronously.

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

async function getSlug(text, separator = "-") {
  try {
    const encodedText = encodeURIComponent(text);
    const encodedSeparator = encodeURIComponent(separator);
    const url = `${baseUrl}/slugify?text=${encodedText}&separator=${encodedSeparator}`;

    const response = await fetch(url, {
      method: "GET",
      headers: {
        "x-api-market-key": apiKey
      }
    });

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

    return await response.json();
  } catch (error) {
    console.error("Error generating slug:", error);
    throw error;
  }
}

// Example usage
(async () => {
  try {
    const result1 = await getSlug("My Awesome Blog Post Title!");
    console.log("Slug for 'My Awesome Blog Post Title!':", result1);
    // Expected output: { original: "My Awesome Blog Post Title!", slug: "my-awesome-blog-post-title", length: 26 }

    const result2 = await getSlug("Produit spécial à vendre", "_");
    console.log("Slug for 'Produit spécial à vendre':", result2);
    // Expected output: { original: "Produit spécial à vendre", slug: "produit_special_a_vendre", length: 24 }

    // Example with missing text (will throw an error)
    // const result3 = await getSlug("");
    // console.log(result3);

  } catch (error) {
    console.error("Failed to process slug:", error);
  }
})();
```

#### Python
```python
import requests
import json

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

def get_slug(text: str, separator: str = "-"):
    headers = {
        "x-api-market-key": API_KEY
    }
    params = {
        "text": text,
        "separator": separator
    }

    response = requests.get(
        f"{BASE_URL}/slugify",
        headers=headers,
        params=params
    )

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

    return response.json()

# Example usage
try:
    result1 = get_slug("My Awesome Blog Post Title!")
    print(f"Slug for 'My Awesome Blog Post Title!': {json.dumps(result1, indent=2)}")
    # Expected output: { "original": "My Awesome Blog Post Title!", "slug": "my-awesome-blog-post-title", "length": 26 }

    result2 = get_slug("Produit spécial à vendre", "_")
    print(f"Slug for 'Produit spécial à vendre': {json.dumps(result2, indent=2)}")
    # Expected output: { "original": "Produit spécial à vendre", "slug": "produit_special_a_vendre", "length": 24 }

    # Example health check
    health_response = requests.get(f"{BASE_URL}/health", headers={"x-api-market-key": API_KEY})
    if health_response.status_code == 200:
        print(f"Health check successful: {health_response.json()}")
    else:
        print(f"Health check failed: {health_response.status_code} {health_response.text}")

except Exception as e:
    print(f"Failed to process slug: {e}")
```
## cURL

### Generate a basic slug

```bash
curl -X GET "https://prod.api.market/api/v1/viv-data/slug/slugify?text=Hello%20World!" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response**

```json
{
  "original": "Hello World!",
  "slug": "hello-world",
  "length": 11
}
```

---

### Generate a slug with a custom separator

> URL-encode special characters such as spaces, `&`, and non-ASCII characters (for example, `%C3%A9` represents `é`).

```bash
curl -X GET "https://prod.api.market/api/v1/viv-data/slug/slugify?text=Caf%C3%A9%20%26%20Restaurant&separator=_" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response**

```json
{
  "original": "Café & Restaurant",
  "slug": "cafe_restaurant",
  "length": 15
}
```

---

### Check the API health

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

**Example Response**

```json
{}
```

### Performance Optimization
*   **Batching (if applicable):** While this API processes one string at a time, for scenarios involving many slugs, consider parallelizing your requests if your application design allows.
*   **Caching:** For static or frequently requested slug conversions (e.g., categories, tags), cache the API responses on your end to reduce redundant API calls and latency.
*   **Error Handling and Retries:** Implement robust error handling with exponential backoff for transient errors (like `429` or `503`) to gracefully manage API limits and service interruptions.

## FAQ

**Q: What is a URL-friendly slug?**

A: A URL-friendly slug is a simplified, human-readable, and URL-compatible version of a title or string. It typically uses lowercase letters, replaces spaces with hyphens (or underscores), and removes special characters, making it ideal for web addresses.

**Q: Does the API support all languages?**

A: The API is designed to handle Unicode characters and diacritics, making it highly effective for many languages. It attempts to convert non-ASCII characters to their closest ASCII equivalents.

**Q: Can I customize the word separator?**

A: Yes, you can specify a custom `separator` in your request if you prefer something other than the default hyphen (`-`).

**Q: Is there a limit to the length of the input text?**

A: While there isn't a strict documented limit, very long strings might be impractical for URL slugs. It's recommended to keep input text to reasonable lengths typically used for titles or descriptions.

**Q: How do I handle errors from the API?**

A: The API returns standard HTTP status codes and detailed JSON error messages. Refer to the "Status Codes" and "Error Handling" sections for guidance on interpreting and resolving errors.

**Q: Is the API synchronous or asynchronous?**

A: This API operates in a synchronous mode, meaning each request returns the final slug directly in the response without any polling required.

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

Convert any text string into clean, URL-friendly slugs instantly. This API masterfully handles Unicode, special characters, and diacritics for robust, SEO-frien

Text to Slug API | Convert Text to URL Slugs, Unicode Safe

Free

Viv Data

Instantly convert text to URL-friendly slugs, masterfully handling Unicode, special characters, and diverse languages for robust, consistent web links.