# Urban Dictionary Scraper: Slang Definitions & Votes (`recordsdata/urban-dictionary-scraper`) Actor

Scrape Urban Dictionary: slang definitions per term with examples, authors, written dates and permalinks, plus words of the day and random discovery. Export CSV, Excel, JSON, XML. No login or API key. Up to 50 definitions per term; error and empty rows are never charged.

- **URL**: https://apify.com/recordsdata/urban-dictionary-scraper.md
- **Developed by:** [RecordsData](https://apify.com/recordsdata) (community)
- **Categories:** Other, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

<p align="center">
  <img src="https://api.apify.com/v2/key-value-stores/AAm3a1h3Z9nYfrvh9/records/banner?v=3" alt="PunkRecordsData" width="100%" />
</p>

## 📕 Urban Dictionary Scraper: Slang Definitions, Examples & Dates

> **Urban Dictionary Scraper is an Apify actor that exports slang definitions for any list of words: definition text, usage example, author, written date and permalink, in Urban Dictionary's own ranking order. It also pulls the words of the day and random entries. No login, no API key. Export CSV, Excel, JSON, XML or use the API. Priced $0.015 per definition row; misses and errors are free.**

The Urban Dictionary Scraper reads Urban Dictionary's public JSON API and turns a list of slang terms into a clean dataset: up to 50 definitions per term, each with example, author, date and link. A 10-row test run in the Apify cloud returned 10 definitions for "rizz" and "sigma" and cost $0.15 in result events. It is built for trust and safety teams, marketers, NLP researchers and anyone who needs slang meanings in bulk instead of one browser tab at a time.

### 🔎 What does the Urban Dictionary Scraper do?

- **Look up slang terms in bulk.** Paste a list of words or phrases such as `rizz`, `sigma`, `mid` and get the top definitions for each.
- **Control depth per term.** Ask for 1 to 50 definitions per term.
- **Export words of the day.** One switch adds the current featured entries as rows.
- **Sample random definitions.** Pull up to 500 random entries for lexicon sampling and trend research.
- **Skip empty and duplicate rows.** A term with no definition returns a free note row. Duplicates are removed before you are charged.
- **Stop at your budget.** The run ends cleanly when your max total charge or `maxItems` is reached.

### 📊 What data can you extract from Urban Dictionary?

| Field | Meaning |
|---|---|
| `recordType` | `definition`, `word-of-the-day` or `random` |
| `term` | The slang word or phrase |
| `rank` | Position among the term's definitions (definition rows) |
| `definition` | Definition text with Urban Dictionary link brackets removed |
| `example` | Usage example (omitted when the entry has none) |
| `author` | Username of the contributor |
| `definitionId` | Urban Dictionary definition id, unique per entry |
| `writtenOn` | ISO date when the definition was written |
| `url` | Permalink to the definition |
| `thumbsUp`, `thumbsDown`, `approvalPercent` | Vote data, present only when the source returns votes (see the note below) |
| `scrapedAt` | UTC timestamp of the run |

Optional fields are left out instead of filled with placeholders, so you never see fake "N/A" values.

**Important note on votes.** When this README was updated (October 2026), Urban Dictionary's public API returned 0 thumbs up and 0 thumbs down for every definition we tested, both from a local machine and from Apify's cloud. The actor therefore leaves the vote columns out instead of reporting false zeros. If Urban Dictionary restores vote counts, `thumbsUp`, `thumbsDown` and `approvalPercent` appear automatically, and the minimum-upvotes filter becomes useful again. Until then, definitions come back in the order Urban Dictionary itself returns them, and `minThumbsUp` above 0 will return nothing.

### 🧾 Sample output of the Urban Dictionary Scraper

A real row from a cloud run with the terms `rizz` and `sigma`:

```json
{
  "recordType": "definition",
  "term": "Rizz",
  "definition": "Another word for spitting game/how good you are with pulling and sustaining bitches.",
  "example": "Person 1: are you from Tennessee cuz u the only ten i see ;) Person watching from a far:Damn, that nigga has no rizz",
  "author": "bro got no rizz",
  "definitionId": "17115763",
  "writtenOn": "2022-03-31T10:36:17.000Z",
  "url": "https://www.urbandictionary.com/define.php?term=Rizz&defid=17115763",
  "rank": 1,
  "scrapedAt": "2026-10-04T05:12:07.023Z"
}
```

Urban Dictionary is user-generated, so definitions can be explicit or offensive. Filter the dataset before showing it to end users.

### 💰 How much does it cost to scrape Urban Dictionary?

The actor uses pay-per-event pricing. You pay only for rows that are saved.

| Event | What is charged | Price per row (Free plan) |
|---|---|---|
| `definition-record` | One definition from a term lookup | $0.015 |
| `discovery-record` | One word-of-the-day or random definition | $0.015 |

That is $15 per 1,000 rows on the Free plan, with lower per-row prices on paid Apify plans (down to $0.01313 on Gold and above). Not charged: error rows, terms with no match, duplicates and rows missing a definition. A 10-row run costs $0.15 in result events. Set a max total charge on the run and it stops when the budget is reached. Free Apify users are limited to 10 rows per run.

### 🚀 How to scrape Urban Dictionary in 3 steps

1. Open the actor on Apify and click **Try for free**.
2. Enter your terms (one per line), choose definitions per term, and optionally switch on words of the day or random definitions.
3. Click **Start**, then download the dataset as CSV, Excel, JSON or XML.

### ⚙️ Urban Dictionary Scraper input

| Field | Type | Default | What it does |
|---|---|---|---|
| `terms` | array | none | Slang words or phrases to look up |
| `maxDefinitionsPerTerm` | integer | 10 | Definitions kept per term (1 to 50) |
| `minThumbsUp` | integer | 0 | Minimum upvotes (see the votes note above) |
| `includeWordsOfTheDay` | boolean | false | Add the current words of the day |
| `randomCount` | integer | 0 | Number of random definitions (0 to 500) |
| `maxItems` | integer | none | Cap on rows for the whole run |

At least one of `terms`, `includeWordsOfTheDay` or `randomCount` is required. An empty input fails immediately with a clear message and costs nothing.

```json
{
  "terms": ["rizz", "sigma"],
  "maxDefinitionsPerTerm": 5,
  "maxItems": 10
}
```

### 📦 Urban Dictionary Scraper output

Every run writes one dataset. The Overview view shows type, term, rank, definition, example, date and link in a table. A run where a term has no definition adds one note row with an `error` field for that term and charges nothing. If Urban Dictionary cannot be reached and no rows were delivered, the run fails instead of finishing empty.

### ⚖️ Urban Dictionary scraper vs alternatives

We checked the public pricing of the other Urban Dictionary actors on the Apify Store on 2026-10-04:

| Actor | Price model | Price per 1,000 rows |
|---|---|---|
| apidojo/urbandictionary-scraper | pay per event | $1.00 |
| ninhothedev/urban-dictionary-scraper | pay per event + start fee | $0.50 |
| muhammadafzal/urban-dictionary-definitions-scraper | pay per event + start fee | $2.00 |
| parseforge/urbandictionary-definitions-scraper | pay per event | $12.00 |
| **PunkRecordsData (this actor)** | pay per event | **$15.00** |

We are the most expensive on price per row. What the extra buys: you are never charged for error, empty, duplicate or incomplete rows, the run stops cleanly at your budget, input is validated before any charge, and one actor covers term lookups, words of the day and random sampling. If you only need a few thousand plain rows and the cheapest price matters most, one of the lower-priced actors may suit you better.

### 💼 Urban Dictionary use cases

- **Moderation lexicons.** Collect meanings of emerging slang so filters and reviewers know what a word signals.
- **Campaign vetting.** Check candidate brand names and taglines for a second meaning before launch.
- **NLP and language research.** Build slang datasets with examples and dates for classifiers, embeddings or glossaries.
- **Trend tracking.** Schedule the words of the day export daily and track new slang over time.

### 🔌 Run the Urban Dictionary Scraper via API and integrations

Call it from any language with the Apify API:

```bash
curl -X POST "https://api.apify.com/v2/acts/recordsdata~urban-dictionary-scraper/run-sync-get-dataset-items?token=<YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"terms":["rizz","sigma"],"maxDefinitionsPerTerm":5,"maxItems":10}'
```

Schedule runs in the Apify Console, or connect the dataset to Zapier, Make, n8n, Google Sheets or Slack. AI agents can call the actor through the Apify MCP server using its input schema, which has descriptions for every field.

### ⚖️ Is it legal to scrape Urban Dictionary?

The actor calls Urban Dictionary's public API at a low rate (one request every half second) and collects only public definitions and usernames shown on the site. It does not log in or bypass protection. Definitions are user-generated content, so credit Urban Dictionary and check its terms of service before republishing text commercially. You are responsible for how you use the data.

### ❓ Frequently asked questions

#### Why do I get 0 results from the Urban Dictionary Scraper?

Either the term has no entry on Urban Dictionary, or you set `minThumbsUp` above 0 while Urban Dictionary reports 0 votes everywhere. The run finishes as succeeded with a status message and charges nothing. Try a different spelling or set `minThumbsUp` to 0.

#### Why are thumbsUp and approvalPercent missing?

Urban Dictionary's API currently returns 0 votes for all definitions, so the actor omits those columns instead of showing fake zeros. They return automatically when the source provides votes.

#### How are definitions ordered?

By Urban Dictionary's own order for the term, then by votes when votes exist. `rank` shows the position per term.

#### Do I need an Urban Dictionary account or API key?

No. The actor works without login or key.

#### How many definitions can I get per term?

Up to 50 with `maxDefinitionsPerTerm`. The source may return fewer for rare words.

#### What are words of the day and random mode?

Words of the day are the featured entries on Urban Dictionary right now. Random mode pulls random entries, useful for sampling the lexicon. Both are charged as `discovery-record`.

#### Am I charged for terms that are not found?

No. Not-found notes, errors and duplicates are saved without a charge, and a run that fails to reach the source delivers nothing and charges nothing.

#### Can I try it for free?

Yes. Free Apify accounts get a 10-row preview per run, and new accounts include free platform credit.

### 🧩 Want more text and reference data? Other PunkRecordsData scrapers

- [Wikipedia Articles Scraper](https://apify.com/RecordsData/wikipedia-articles-scraper) for article text and metadata.
- [Hacker News Search Scraper](https://apify.com/RecordsData/hackernews-search-scraper) for stories, comments and trends.
- [Wayback Machine Scraper](https://apify.com/RecordsData/wayback-machine-scraper) for archived page snapshots.

### 🛟 Support

Found a bug or a missing field? Open the **Issues** tab on this actor's page, or write to contact.punkrecordsdata@gmail.com. Custom solutions are available on request.

Last updated: 2026-10-03

# Actor input Schema

## `terms` (type: `array`):

Slang words or phrases to look up on Urban Dictionary, one per line (for example rizz, sigma, mid). Leave empty only if you enable words of the day or random definitions.

## `maxDefinitionsPerTerm` (type: `integer`):

How many definitions to return for each term, taken from the highest upvoted ones first (1 to 50, default 10).

## `minThumbsUp` (type: `integer`):

Only return definitions with at least this many thumbs up (0 returns every definition). Note: Urban Dictionary currently reports 0 votes for all definitions, so any value above 0 returns nothing until votes are restored.

## `includeWordsOfTheDay` (type: `boolean`):

Also export the current Urban Dictionary words of the day as rows (recordType word-of-the-day).

## `randomCount` (type: `integer`):

Number of random Urban Dictionary definitions to export for discovery and lexicon sampling (0 turns it off, max 500).

## `maxItems` (type: `integer`):

Maximum number of rows to return and be charged for across the whole run. Free users are limited to 10 rows (preview). Paid users: optional, up to 1,000,000.

## Actor input object example

```json
{
  "terms": [
    "rizz",
    "sigma"
  ],
  "maxDefinitionsPerTerm": 10,
  "minThumbsUp": 0,
  "includeWordsOfTheDay": false,
  "randomCount": 0,
  "maxItems": 10
}
```

# Actor output Schema

## `overview` (type: `string`):

Key fields per row

## `fullData` (type: `string`):

Complete dataset with all fields

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "terms": [
        "rizz",
        "sigma"
    ],
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("recordsdata/urban-dictionary-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "terms": [
        "rizz",
        "sigma",
    ],
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("recordsdata/urban-dictionary-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "terms": [
    "rizz",
    "sigma"
  ],
  "maxItems": 10
}' |
apify call recordsdata/urban-dictionary-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,recordsdata/urban-dictionary-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/O4f5Uvxqc0vsNBfqs/builds/Iq6mdYetOPQHxhb66/openapi.json