What is PurgoMalum?

PurgoMalum is a simple, free, RESTful web service for filtering and removing content of profanity, obscenity and other unwanted text.
PurgoMalum's interface accepts several parameters for customization and can return results in plain text, XML and JSON.

PurgoMalum is designed to remove words from input text, based on an internal profanity list (you may optionally add your own
words to the profanity list through a request parameter (see Request Parameters below). It is designed to recognize character alternates often used
in place of standard alphabetic characters, e.g. "@" will be recognized as an "a", "$" will be recognized as an "s", and so forth.

PurgoMalum also utilizes a list of "safe words", i.e. innocuous words which contain words from the profanity list ("class" for example).
These safe words are excluded from the filter.

If you discover any bugs or have any concerns, please contact me, and I will do my best to address them.

Usage

Calling the Web Service

Calling the web service involves a simple HTTP GET request. The only two requirements for using PurgoMalum are
the "text" parameter on the query string and the request-type name as part of the path in the request.
Here is a basic example of a request call to PurgoMalum, which will return the result as XML:

http://www.purgomalum.com/service/xml?text=this is some test input

Note the return type within the request URL - "xml" - and the required parameter "text".

Request Parameters

This is a current list of available parameters which can be used in the request query string:

Parameter

Required?

Description

text

Required

Input text to be processed.

add

Optional

A comma separated list of words to be added to the profanity list. Accepts letters, numbers, underscores (_) and commas (,). Accepts up to 10 words (or 200 maximum characters in length). The PurgoMalum filter is case-insensitive, so the case of you entry is not important.

Single character used to replace any words matching the profanity list. Fills designated character to length of word replaced. Accepts underscore (_) tilde (~), dash/hyphen (-), equal sign (=), pipe (|) and asterisk (*). When not used, the default is an asterisk (*) fill.

Response Types

This is a current list of methods provided by the web service and their corresponding return type:

XMLResponse

JSON Request

http://www.purgomalum.com/service/json?text=this is some test input&add=input&fill_char=_

JSON Response

{"result":"this is some test _____"}

Error Handling

When an error occurs - caused by either invalid user input or generated within the application -
PurgoMalum will not return the "results" element, but instead will return the "error" element
with an associated error message.

Here is an example of a request using an invalid parameter, causing an error response:

Request

http://www.purgomalum.com/service/xml?text=this is some test input&fill_text=this is curiously long replacement text

Response

Contact

Please contact me with any questions, concerns or suggestions. If you encounter a
response that is unusual or erroneous, please send me the exact text and optional parameters
(if any) you used to make the request.