Metal Archives Ruby API

Continuous Integration Release

MetalArchives is a Ruby API that transparently wraps, caches and normalizes the Metal Archives website.


Add this line to your application's Gemfile.

gem "metal_archives"

And then execute:


Or install it yourself as:

gem install metal_archives


Configure MetalArchives before using it:

MetalArchives.configure do |c|
  ## Application identity (required)
  c.app_name = "My App"
  c.app_version = "1.0"
  c.app_contact = "[email protected]"

  ## Enable Redis as caching backend (optional, overrides default memory cache)
  ## Available cache strategies: :memory, :redis or :null (disable caching)
  # c.cache_strategy = :redis
  # c.cache_options = { url: "redis://redis:6379", ttl: 1.month.to_i }

  ## Metal Archives endpoint (optional, overrides default)
  # c.endpoint = ""
  # c.endpoint_user = "my_user"
  # c.endpoint_password = "my_password"

  ## Custom logger (optional)
  c.logger ="metal_archives.log")
  c.logger.level = Logger::INFO


require "metal_archives"

# Search for bands
@alquimia_list ="Alquimia")

# Find bands by name
@iron_maiden = MetalArchives::Band.find_by(name: "Iron Maiden")

# Find bands by attributes
require "countries"

@bands_in_belgium = MetalArchives::Band.search_by(country: ISO3166::Country["BE"])
@bands_formed_in_1990 = MetalArchives::Band.search_by(year: 1990..)

# Metal Archives' usual tips apply

@bands_containing_hell = MetalArchives::Band.search_by name: "*hell*"
@non_melodic_death_bands = MetalArchives::Band.search_by genre: "death -melodic"

# Methods returning multiple results return a MetalArchives::Collection.
# Collection wraps a paginated resource, and can be used to iterate over huge queries.
@non_melodic_death_bands.first(100).each do |band|

Refer to the model's RDoc documentation.

Lazy loading

By default when an model (Artist, Band, ...) is created, no data is fetched. This leads to instantiation of a model with an invalid ID not throwing any errors. Calling any attribute other than id will cause all data to be fetched and any errors to be thrown. Refer to the respective methods to find out what errors are thrown in what circumstances.

Models can be forced to load all data by calling the load! method.


The gem has builtin caching functionality. By default, an in-memory cache is used that evicts cache entries using an LRU-based algorithm. However, it is also possible to use Redis as a caching backend. Don't forget to include the redis gem in your application bundle if you wish to use Redis caching.

In order not to stress the Metal Archives server, you can quickly set up a local HTTP proxy that caches the requests.

# Generate TLS client certificates for NGINX
openssl req -nodes -new -x509  -keyout nginx/client.key -out nginx/client.pem

# Start proxy server
docker-compose up -d

A caching proxy server is now available on http://localhost:8080/.


Run tests:

bundle exec rake test


Generate documentation:

$ bundle exec rake rdoc