urban-dictionary
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/urban-dictionary package

    3.0.2 • Public • Published

    urban-dictionary

    contributions github-issue npm-license npm-version npm-downloads

    JavaScript Style Guide

    Badges from: NodeICO, standard JS and Shields IO

    What's New

    v3.0.0

    • Module rewritten with more up-to-date ES6 features.
    • Module size has been reduced slightly.
    • New methods have been added with the help from this posted issue.
    • At some point. Urban had stopped providing sounds and tags with certain methods. These have been removed from the module.
    • The following methods have been renamed for clarity.
    • The code has been updated to reflect on StandardJS new standards.
    • Better layout and formatting of this README.md file.
    • Included example.js to be included in the npm package.
    • For developers of this module.
      • I've removed debug.js and split the methods into separate .js files under ./test for easier debugging.
      • I've included a urls.txt file under ./test for a list of known Urban URLs.
      • I've added some vscode automated project rules to make sure the tab spaces are correct.

    Be sure to check the README.md (this document). Methods from v2.2.1 may will not work on v3.0.0.

    Installing

    Via NPM (Recommended)

    Install Node.js with the NPM extra component. This is included by default during a default install on Windows. Then open your command terminal and use one of the following. Local is for the current project folder. Global will install and work on all your projects that require the module.

    Local Install: npm install urban-dictionary

    Global Install npm install urban-dictionary -g

    Local Uninstall npm uninstall urban-dictionary

    Global Uninstall npm uninstall urban-dictionary -g

    If you're installing locally. Be sure to run npm init in the top directory of the project to avoid issues.

    Via Downloadable Zip

    Download the latest release from GitHub and extract the urban-dictionary.js into your project folder. Beware that you have got to require('./urban-dictionary') with the ./ prefix for local directory when you install by zip.

    Actions

    autocomplete

    Use this to retrieve an array up to 20 search suggested strings.

    Arguments

    • term String The term to lookup.
    • callback Function
      • error Error if there's an error else null.
      • results Array of String

    Return

    • return Promise if no Function is provided for callback.
      • then Array of String
      • catch Error

    E.g.

    'use strict'
    
    const ud = require('urban-dictionary')
    
    // Callback
    ud.autocomplete('test', (error, results) => {
      if (error) {
        console.error(`autocomplete (callback) error - ${error.message}`)
        return
      }
    
      console.log('autocomplete (callback)')
    
      console.log(results.join(', '))
    })
    
    // Promise
    ud.autocomplete('test').then((results) => {
      console.log('autocomplete (promise)')
    
      console.log(results.join(', '))
    }).catch((error) => {
      console.error(`autocomplete (promise) - error ${error.message}`)
    })

    autocompleteExtra

    Use this to retrieve an array up to 20 search suggested AutocompleteExtraObject that contain a preview and suggested term.

    Arguments

    • term String The term to lookup.
    • callback Function

    Return

    E.g.

    'use strict'
    
    const ud = require('urban-dictionary')
    
    // Callback
    ud.autocompleteExtra('test', (error, results) => {
      if (error) {
        console.error(`autocomplete (callback) - ${error.message}`)
        return
      }
    
      console.log('autocompleteExtra (callback)')
    
      results.forEach(({ preview, term }) => {
        console.log(`${term} - ${preview}`)
      })
    })
    
    // Promise
    ud.autocompleteExtra('test').then((results) => {
      console.log('autocompleteExtra (promise)')
    
      results.forEach(({ preview, term }) => {
        console.log(`${term} - ${preview}`)
      })
    }).catch((error) => {
      console.error(`autocomplete (promise) - ${error.message}`)
    })

    define

    Use this to retrieve an array up to 10 DefinitionObject.

    Arguments

    • term String The definition to lookup.
    • callback Function

    Return

    • return Promise if no Function is provided for callback.

    E.g.

    'use strict'
    
    const ud = require('urban-dictionary')
    
    // Callback
    ud.define('test', (error, results) => {
      if (error) {
        console.error(`define (callback) error - ${error.message}`)
        return
      }
    
      console.log('define (callback)')
    
      Object.entries(results[0]).forEach(([key, prop]) => {
        console.log(`${key}: ${prop}`)
      })
    })
    
    // Promise
    ud.define('test').then((results) => {
      console.log('define (promise)')
    
      Object.entries(results[0]).forEach(([key, prop]) => {
        console.log(`${key}: ${prop}`)
      })
    }).catch((error) => {
      console.error(`define (promise) - error ${error.message}`)
    })

    getDefinitionByDefid

    Use this to retrieve a specific DefinitionObject by its defid.

    Arguments

    • defid Number The definition defid to retrieve.
    • callback Function

    Return

    • return Promise if no Function is provided for callback.

    E.g.

    'use strict'
    
    const ud = require('urban-dictionary')
    
    // Callback
    ud.getDefinitionByDefid(217456, (error, result) => {
      if (error) {
        console.error(`getDefinitionByDefid (callback) error - ${error.message}`)
        return
      }
    
      console.log('getDefinitionByDefid (callback)')
    
      Object.entries(result).forEach(([key, prop]) => {
        console.log(`${key}: ${prop}`)
      })
    })
    
    // Promise
    ud.getDefinitionByDefid(217456).then((result) => {
      console.log('getDefinitionByDefid (promise)')
    
      Object.entries(result).forEach(([key, prop]) => {
        console.log(`${key}: ${prop}`)
      })
    }).catch((error) => {
      console.error(`getDefinitionByDefid (promise) - error ${error.message}`)
    })

    random

    Use this to retrieve an array up to 10 random DefinitionObject.

    Arguments

    • callback Function

    Return

    • return Promise if no Function is provided for callback.

    E.g.

    'use strict'
    
    const ud = require('urban-dictionary')
    
    // Callback
    ud.random((error, results) => {
      if (error) {
        console.error(`random (callback) error - ${error.message}`)
        return
      }
    
      console.log('random (callback)')
    
      Object.entries(results[0]).forEach(([key, prop]) => {
        console.log(`${key}: ${prop}`)
      })
    })
    
    // Promise
    ud.random().then((results) => {
      console.log('random (promise)')
    
      Object.entries(results[0]).forEach(([key, prop]) => {
        console.log(`${key}: ${prop}`)
      })
    }).catch((error) => {
      console.error(`random (promise) - error ${error.message}`)
    })

    wordsOfTheDay

    Use this to retrieve an array with 10 Words of the Day DefinitionObject.

    Arguments

    • callback Function

    Return

    • return Promise if no Function is provided for callback.

    E.g.

    'use strict'
    
    const ud = require('urban-dictionary')
    
    // Callback
    ud.wordsOfTheDay((error, results) => {
      if (error) {
        console.error(`wordsOfTheDay (callback) error - ${error.message}`)
        return
      }
    
      console.log('wordsOfTheDay (callback)')
    
      Object.entries(results[0]).forEach(([key, prop]) => {
        console.log(`${key}: ${prop}`)
      })
    })
    
    // Promise
    ud.wordsOfTheDay().then((results) => {
      console.log('wordsOfTheDay (promise)')
    
      Object.entries(results[0]).forEach(([key, prop]) => {
        console.log(`${key}: ${prop}`)
      })
    }).catch((error) => {
      console.error(`wordsOfTheDay (promise) - error ${error.message}`)
    })

    FAQ

    • Q: Where did you get the URL to access Urban Dictionary's API? They hadn't got a documented page.
      • A: I just found them floating around on the web years ago. I don't have a source, sorry.
    • Q: Are there any more methods?
      • A: These are the only URL methods that I'm aware of: test/urls.txt.
    • Q: If they haven't documented it. Are we even allowed to use their site API?
      • A: I don't really know the answer. However, sites nowadays use an authorization name and password in the URL queries to restrict their API access to certain individuals. If Urban Dictionary didn't want others using it, they would had done so by now. In short: As long as we don't abuse the API to spam requests, we should be fine.
    • Q: Why use StandardJS coding style?
      • A: There are many different coding rules of JavaScript being used today. Since this standard is being used by many packages and is becoming common on github. I've decided to start using it myself and quickly started to like it. It saves time by not having to worry which rules to follow or finding ways around strict styles such as JSLint.
    • Q: One of the methods isn't working?
      • A: Give it a day or two. The chances are that api.urbandictionary.com is down. It has happened before after I thought they removed one of their URL methods. If it's still not working after two days, post an issue and I'll check it out.
    • Q: Is it possible to use both callback and promise at the same time?
      • A: This feature is no longer available and was removed after v2.1.1 since it leads to poor coding practices and should be avoided.

    Object Dictionary

    AutocompleteExtraObject

    Name Type Explanation
    preview String An example usage of the term possibility.
    term String An auto complete term possibility.

    DefinitionObject

    Be aware that the date property is only available for the wordsOfTheDay method.

    Name Type Explanation
    author String Name of the definition poster.
    current_vote String Unknown.
    date String The date when this definition was posted on Words of the Day.
    defid Number The unique ID for this definition.
    definition String An explanation of the term.
    example String An example usage of the definition.
    permalink String Link to the definition page.
    sound_urls Array Presumably an Array of Strings containing URLs. I hadn't seen any results with any data though.
    thumbs_down Number The number of declined votes for the definition.
    thumbs_up Number The number of accepted votes for the definition.
    word String The term used to find this definition.
    written_on String The date the definition was posted. Format: "[YYYY]-[MM]-[DD]T[HH]:[MM]:[SS].[MMM][Z]"

    Install

    npm i urban-dictionary

    DownloadsWeekly Downloads

    1,255

    Version

    3.0.2

    License

    MIT

    Unpacked Size

    21.5 kB

    Total Files

    5

    Last publish

    Collaborators

    • nightfallalicorn