Getting started overview

PurgoMalum provides a RESTful API for basic profanity filtering, designed for quick integration without the need for authentication or an API key. This approach allows developers to send direct HTTP GET requests to its endpoints, making it suitable for educational projects, small applications, and rapid prototyping where straightforward content moderation is required. The service supports filtering text against its default profanity list and offers options for custom word filtering and various output formats.

The core functionality revolves around submitting text via a URL query parameter and receiving a filtered response. This simplicity means that developers can begin integrating PurgoMalum using standard HTTP client libraries available in most programming languages or even directly from a web browser or command-line tools like cURL.

Here’s a quick-reference guide to initiating your PurgoMalum integration:

Step What to do Where
1. Review Documentation Understand API endpoints and parameters. PurgoMalum API documentation
2. Formulate Request Construct a GET request with your text. Your code editor or cURL
3. Send Request Execute the HTTP GET request. Your application, browser, or cURL
4. Process Response Handle the filtered text returned by the API. Your application logic

Create an account and get keys

PurgoMalum does not require an account, API keys, or any form of authentication to use its service. This design choice simplifies the setup process significantly, allowing developers to start making requests immediately upon reviewing the API documentation. The absence of authentication tokens means there are no credentials to create, manage, or secure, which streamlines integration for projects that do not require rate limiting or advanced access control.

This model is distinct from many commercial APIs, which often implement OAuth 2.0 for authorization or require API keys for access control and billing. For PurgoMalum, developers can proceed directly to constructing and sending API requests after understanding the available endpoints and parameters.

To begin, simply reference the PurgoMalum API reference to identify the correct endpoint and query parameters for your desired filtering operation.

Your first request

Making your first request to PurgoMalum involves sending a basic HTTP GET request with the text you wish to filter. The API provides several endpoints and parameters to control the filtering behavior and output format. The fundamental endpoint for text filtering is https://www.purgomalum.com/service/plain?text=.

Filtering plain text

To filter a simple string, append your text as the value of the text query parameter. The API will replace profanity with asterisks (*).

cURL example

curl "https://www.purgomalum.com/service/plain?text=This is some badword text."

Expected response:

This is some ******* text.

Python example

import requests

text_to_filter = "This is some badword text."
api_url = f"https://www.purgomalum.com/service/plain?text={text_to_filter}"

response = requests.get(api_url)

if response.status_code == 200:
    print(response.text)
else:
    print(f"Error: {response.status_code}")

Expected output:

This is some ******* text.

JavaScript (Node.js) example

const fetch = require('node-fetch'); // For Node.js environments

async function filterText() {
  const textToFilter = "This is some badword text.";
  const apiUrl = `https://www.purgomalum.com/service/plain?text=${encodeURIComponent(textToFilter)}`;

  try {
    const response = await fetch(apiUrl);
    if (response.ok) {
      const filteredText = await response.text();
      console.log(filteredText);
    } else {
      console.error(`Error: ${response.status} ${response.statusText}`);
    }
  } catch (error) {
    console.error(`Fetch error: ${error.message}`);
  }
}

filterText();

Expected output:

This is some ******* text.

Filtering with custom replacement character

You can specify a custom replacement character using the add parameter. For example, to replace profanity with #:

cURL example

curl "https://www.purgomalum.com/service/plain?text=This is some badword text.&add=#[char]"

Expected response:

This is some ####### text.

The [char] placeholder in add=#[char] instructs the API to replace each character of the profanity with the specified character. If [char] is omitted, the entire word is replaced by the single character.

Filtering with custom word list

To filter against your own list of words in addition to (or instead of) the default profanity list, use the add parameter with a comma-separated list of words. For instance, to filter 'apple' and 'orange':

cURL example

curl "https://www.purgomalum.com/service/plain?text=I like apple and orange.&add=apple,orange"

Expected response:

I like ***** and ******.

For more advanced filtering options, including different output formats (JSON, XML) and options to return only the filtered words, consult the PurgoMalum documentation.

Common next steps

After successfully making your first request, consider these common next steps to integrate PurgoMalum more effectively into your application:

  1. Explore additional filtering options: The API supports various parameters for customizing the filtering behavior. For example, you can replace profanity with a specific string (e.g., [censored]) instead of asterisks, or retrieve a JSON object containing details about the filtered text. Review the PurgoMalum API documentation for a complete list of parameters like fill_char, fill_text, and different service endpoints (e.g., /service/json for JSON output).

  2. Handle different output formats: While the /service/plain endpoint returns plain text, PurgoMalum also offers /service/json and /service/xml endpoints for structured responses. Adapting your application to parse JSON or XML responses can be beneficial for integrating with front-end frameworks or other services that prefer structured data. For example, a JSON response might look like {"result":"This is some ******* text."}.

  3. Integrate into your application logic: Determine where in your application's data flow the profanity filtering is most appropriate. Common use cases include:

    • Before saving user-generated content to a database.
    • Before displaying user comments or forum posts.
    • When validating input fields in real-time.

    Consider the performance implications of making external API calls and implement appropriate error handling and asynchronous processing if necessary.

  4. Implement client-side vs. server-side filtering: Decide whether to perform filtering on the client-side (e.g., using JavaScript in a web browser) or server-side (e.g., using Python or Node.js on your server). Client-side filtering can provide immediate feedback to users but is less secure as it can be bypassed. Server-side filtering offers better security and ensures all content is checked before storage or display. Given that PurgoMalum is a public API, server-side integration is generally recommended for production applications to maintain control over content moderation policy.

  5. Consider alternatives for advanced needs: While PurgoMalum is excellent for basic, free profanity filtering, projects requiring advanced features like machine learning-based content moderation, image/video analysis, or robust reporting and analytics might need more comprehensive solutions. Services like Sightengine for AI content moderation or WebPurify for commercial-grade filtering offer broader capabilities for complex content moderation pipelines.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps for PurgoMalum:

  1. Check the URL syntax: Ensure the URL is correctly formed. Mistakes in endpoint paths (e.g., /service/plain) or query parameter names (e.g., text=, add=) can lead to unexpected results or errors. Verify that special characters in your text are URL-encoded. For example, spaces should be %20.

  2. Verify network connectivity: Confirm that your environment has internet access and can reach https://www.purgomalum.com. A simple test is to open the API URL in a web browser (e.g., https://www.purgomalum.com/service/plain?text=test) to see if you receive a response.

  3. Review HTTP status codes: While PurgoMalum is designed to be simple, an HTTP status code other than 200 OK indicates an issue. Common codes to look out for include:

    • 400 Bad Request: Often due to malformed URLs or invalid parameters.
    • 404 Not Found: The requested endpoint does not exist.
    • 5xx Server Error: An issue on the PurgoMalum server side.

  4. Examine API response content: If you receive a 200 OK status but the output isn't what you expect, inspect the response body. Ensure that the text you submitted was correctly received and processed. For example, if you're expecting custom words to be filtered but they aren't, check that the add parameter was correctly formatted and included in the request.

  5. Isolate the issue: Try the simplest possible request (e.g., curl "https://www.purgomalum.com/service/plain?text=badword"). If this works, gradually add more complexity (custom words, different output formats) until the issue reappears, helping you pinpoint the problematic parameter or configuration.

  6. Consult official documentation: The PurgoMalum API documentation is the authoritative source for all endpoints, parameters, and expected behaviors. Cross-reference your request with the examples and descriptions provided there.