wallhaven-client

wallhaven.cc HTTP Client

Table of Contents

• API
• Arguments
  • search / wallpaper / image / login / favorites
• Examples

API

Name | Arguments | Returns | Description :--- | :--- | :--- | :--- search | {q, categories, purity, resolutions, atleast, ratios, colors, sorting, topRange, order, page, ...options} | {Object} | Filter wallpapers wallpaper | {id, ...options} | {Object} | Get full meta data about wallpaper image | {id, size, ext, location, ...options} | writes to file | Download single image login | {user, pass, ...options} | cookie string | Login to Wallhaven favorites | {id, page, cookie, ...options} | {Object} | Get meta data about user's collections and the wallpapers in them

var wh = require('wallhaven-client')

;(async () => {
  var {count, total, pages, tags, wallpapers} = await wh.search({q: 'steampunk'})
  var meta = await wh.wallpaper({id: '527712'})
  await wh.image({id: '527712'})
  var cookie = await wh.login({user, pass})
  var {collections, wallpapers, pages} = await wh.favorites({cookie})
})()

{
  count: 24,
  total: 144,
  pages: 6,
  tags: [ { id: '874', name: 'steampunk', purity: 'sfw' } ],
  wallpapers: [
    { id: '102569',
      purity: 'sfw',
      category: 'general',
      resolution: '1920x1080',
      favorites: 243,
      urls:
       { page: 'https://alpha.wallhaven.cc/wallpaper/102569',
         thumb: 'https://alpha.wallhaven.cc/wallpapers/thumb/small/th-102569.jpg',
         full: 'https://wallpapers.wallhaven.cc/wallpapers/full/wallhaven-102569.jpg',
         short: 'https://whvn.cc/102569' } },
    { id: '1182',
      purity: 'sfw',
      category: 'general',
      resolution: '2560x1600',
      favorites: 123,
      urls:
       { page: 'https://alpha.wallhaven.cc/wallpaper/1182',
         thumb: 'https://alpha.wallhaven.cc/wallpapers/thumb/small/th-1182.jpg',
         full: 'https://wallpapers.wallhaven.cc/wallpapers/full/wallhaven-1182.jpg',
         short: 'https://whvn.cc/1182' } }
  ]
}

{
  id: '651423',
  resolution: '2000 x 1285',
  ratio: undefined,
  category: 'Anime',
  purity: 'sfw',
  size: '5.1 MiB',
  views: '700',
  favorites: '6',
  tags:
   [ { id: '1', name: 'anime', purity: 'sfw' },
     { id: '45595', name: 'Macross Delta', purity: 'sfw' },
     { id: '54814', name: 'Kaname Buccaneer', purity: 'sfw' },
     { id: '45559', name: 'Mikumo Guynemer', purity: 'sfw' },
     { id: '74518', name: 'Makina Nakajima', purity: 'sfw' },
     { id: '49846', name: 'Freyja Wion', purity: 'sfw' },
     { id: '74689', name: 'Reina Prowler', purity: 'sfw' },
     { id: '5063', name: 'Macross', purity: 'sfw' } ],
  colors: [ 'abbcda', 'cccccc', 'ffffff', '66cccc', '999999' ],
  source: 'https://www.pixiv.net/member_illust.php?mode=medium&illust_id=65239432',
  uploader:
   { username: 'AksumkA',
     avatar: 'https://static.wallhaven.cc/images/user/avatar/32/2_82aff6c49745ac98ef5dda356aabed354de0f398c783ef8e9d4d8b734c283074.png',
     group: 'owner',
     profile: 'https://alpha.wallhaven.cc/user/AksumkA' },
  date: '2018-05-06T21:11:47+00:00',
  urls:
   { page: 'https://alpha.wallhaven.cc/wallpaper/651423',
     thumb: 'https://alpha.wallhaven.cc/wallpapers/thumb/small/th-651423.jpg',
     full: 'https://wallpapers.wallhaven.cc/wallpapers/full/wallhaven-651423.png',
     short: 'https://whvn.cc/651423' },
  ext: 'png'
}

{
  collections: [
    { id: '121373', name: 'Default', private: true, total: 40 },
    { id: '308194', name: 'Science', public: true, total: 9 } ],
  wallpapers: [
    { id: '703709',
      purity: 'sfw',
      category: 'general',
      resolution: '3353x1588',
      favorites: 129,
      urls:
       { page: 'https://alpha.wallhaven.cc/wallpaper/703709',
         thumb: 'https://alpha.wallhaven.cc/wallpapers/thumb/small/th-703709.jpg',
         full: 'https://wallpapers.wallhaven.cc/wallpapers/full/wallhaven-703709.jpg',
         short: 'https://whvn.cc/703709' } }
  ],
  pages: 2
}

Arguments

search

Parameter | Value :- | :- q | any search term, or tag id id:853, @username, type:{png/jpg/jpeg} categories | see below purity | see below resolutions | 1920x1080 or 1920x1080,1920x1200 atleast | 1920x1080 ratios | 16x9 or 16x9,16x10 colors | 660000, 990000, cc0000, cc3333, ea4c88, 993399, 663399, 333399, 0066cc, 0099cc, 66cccc, 77cc33, 669900, 336600, 666600, 999900, cccc33, ffff00, ffcc33, ff9900, ff6600, cc6633, 996633, 663300, 000000, 999999, cccccc, ffffff, 424153 sorting | relevance, random, date_added, views, favorites, toplist topRange | 1d, 3d, 1w, 1M, 3M, 6M, 1y, only available for sorting=toplist order | desc, asc page | any number ...options | agent, timeout (any request-compose option)

Parameter / Value | 000 | 100 | 010 | 001 | 111 :- | :-: | :-: | :-: | :-: | :-: categories | none | general | anime | people | all purity | none | sfw | sketchy | nsfw | all

+ any combination

Note that currently there is no information on the search page about the actual file extension of the wallpaper. The urls.full key will always point to an image with .jpg file extension. The image download API however will retry to download the image with .png file extension if it fails with .jpg.

The search returns up to 24 wallpapers.

wallpaper

Parameter | Value :- | :- id | Wallpaper ID ...options | agent, timeout (any request-compose option)

image

Parameter | Value :- | :- id | Wallpaper ID size | 'thumb' or 'full' (defaults to thumb) ext | 'jpg' or 'png' (defaults to jpg) location | Download location (defaults to process.cwd) ...options | agent, timeout (any request-compose option)

login

Parameter | Value :- | :- user | Username pass | Password ...options | agent, timeout (any request-compose option)

favorites

Parameter | Value :- | :- id | Collection ID page | any number cookie | Session cookie ...options | agent, timeout (any request-compose option)

Examples

search / wallpaper / image / favorites

node examples/search.js [example index]
node examples/wallpaper.js [example index]
node examples/image.js [example index]
node examples/favorites.js [example index]