urban-dictionary/README.md

urban-dictionary

Badges from: NodeICO, standard JS and Shields IO

• What's New
• Installing
• Actions
  • autocompleteExtra
  • autocomplete
  • define
  • getDefinitionByDefid
  • random
  • wordsOfTheDay
• FAQ
• Object Dictionary
  • AutocompleteExtraObject
  • DefinitionObject

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.
  • autocompleteExtra
  • autocomplete
  • words_of_the_day
• 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.
  • defid to getDefinitionByDefid
  • term to define
• 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
  • error Error if there's an error else null.
  • result Array of AutocompleteExtraObject

Return

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

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
  • error Error If there's an error else null.
  • results Array of DefinitionObject

Return

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

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
  • error Error if there's an error else null.
  • result DefinitionObject

Return

• return Promise if no Function is provided for callback.
  • then DefinitionObject
  • catch Error

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
  • error Error If there's an error else null.
  • results Array of DefinitionObject

Return

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

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
  • error Error If there's an error else null.
  • results Array of DefinitionObject

Return

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

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]"