node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »



Build Status

Finding an image for a given URL. imgseeker uses OpenGraph og:image as a fallback if no config for the hostname is given and og:image exists.

Getting Started

Install the module with: npm install imgseeker

var imgseeker = require('imgseeker');
imgseeker.init({});'', function (err, imgUrl)) {
  // do something with imgUrl


Options reference

  • defaultImg: Boolean, indicates if at least the first img on the page should be returned (Default true)
  • request: Object, all properties from mikeal's request module can be used

setting the global config

IMPORTANT: You need to call the init-method () before seeking in an URL. The init-method itself is chainable so you can call imgseeker.init().seek(…

if no config for a hostname is given, imgseeker tries to fetch OpenGraphs og:image, if there is no og:image it tries to fetch the first image of the page (if defaultImg is set to true)

config-values for 1 host can be provided as String or Array. If they are given as an Array, imgseeker loops over the array, and returns the first element with a working selector (tries to get src-property and if not found a background image). if you do not want the first image, specify a zero-based index separated with a pipe in your selector (e.g. '.your-selector|1' would return the second image found for this selector)

var imgseeker = require('imgseeker');
imgseeker.init(); // setting the global config

seek for a img-url from a page'some-url', function (err, imgUrl) {
  // do something with imgUrl

seek for a img-url from a page and define a custom selector (override global config)'some-url', {'some-url': ['.img-class']}function (err, imgUrl) {
  // do something with imgUrl


// init and seek with global config (including some request-config)
var imgseeker = require('imgseeker');
  request: {
    maxConnections: 50,
    followAllRedirects: true,
    encoding: 'utf-8'
  '': ['.some-class > img', '.another-class > img'],
  '': ['img']
}).seek('', function (err, imgUrl) {
  // do something with imgUrl
// seek with special config (which overrides global config)
var specialConfig = {
  '': ['.some-special-selector']
};'', specialConfig, function (err, imgUrl)) {
  // do something with imgUrl
// seek for image 2 which was found for this selector
var specialConfig = {
  '': ['.some-special-selector|2']
};'', specialConfig, function (err, imgUrl)) {
  // do something with imgUrl


In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

  • 0.3.2

    • use background-image if obj has not a src-property
    • add possibility to add index of image to be returned
  • 0.3.1

    • bugfix og:images -> og:image
  • 0.3.0

    • make all request properties available
  • 0.2.1

    • make request timeout settable
  • 0.2.0

    • domain-configs as arrays (existing string configs will still work)
  • 0.1.1

    • resolve img-urls to absolute urls
  • 0.1.0

    • Initial Commit


  • Bastian "hereandnow" Behrens


Copyright (c) 2013 Valiton GmbH Licensed under the MIT license.