{"id":21201669,"url":"https://github.com/oleander/spot","last_synced_at":"2025-07-10T06:31:52.679Z","repository":{"id":56896661,"uuid":"1454969","full_name":"oleander/Spot","owner":"oleander","description":"A Ruby implementation of the Spotify Meta API","archived":false,"fork":false,"pushed_at":"2012-06-26T01:01:13.000Z","size":400,"stargazers_count":9,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-08-11T00:28:56.530Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/oleander/Spot","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oleander.png","metadata":{"files":{"readme":"README.markdown","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-03-08T15:11:42.000Z","updated_at":"2019-04-22T13:08:34.000Z","dependencies_parsed_at":"2022-08-21T01:50:34.069Z","dependency_job_id":null,"html_url":"https://github.com/oleander/Spot","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oleander%2FSpot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oleander%2FSpot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oleander%2FSpot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oleander%2FSpot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oleander","download_url":"https://codeload.github.com/oleander/Spot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225622846,"owners_count":17498168,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-20T20:10:25.906Z","updated_at":"2024-11-20T20:10:26.610Z","avatar_url":"https://github.com/oleander.png","language":"Ruby","readme":"# Spot\n\nA Ruby implementation of the [Spotify Meta API](http://developer.spotify.com/en/metadata-api/overview/).\n\nThis gem is used internally at the [Radiofy](http://radiofy.se) project.\n\nFollow me on [Twitter](http://twitter.com/linusoleander) for more info and updates.\n\n## How to use\n\n### Find a song\n\nThe `Spot::Search.find_song` method returns the first hit.\n\n```` ruby\nSpot::Search.find_song(\"Like Glue\")\n````\n\n### Find all songs\n\nThe `find_all_songs` method returns a list of `Spot::Song` objects.\n\n```` ruby\nSpot::Search.find_all_songs(\"Like Glue\")\n````\n\n### Find an artist\n\nThe `Spot::Search.find_artist` method returns the first hit.\n\n```` ruby\nSpot::Search.find_artist(\"Madonna\")\n````\n\n### Find all artists\n\nThe `find_all_artists` method returns a list of `Spot::Artist` objects.\n\n```` ruby\nSpot::Search.find_all_artists(\"Madonna\")\n````\n\n### Find an album\n\nThe `Spot::Search.find_album` method returns the first hit.\n\n```` ruby\nSpot::Search.find_album(\"Old Skool Of Rock\")\n````\n\n### Find all albums\n\nThe `find_all_albums` method returns a list of `Spot::Album` objects.\n\n```` ruby\nSpot::Search.find_all_albums(\"Old Skool Of Rock\")\n````\n\n### Find best match\n\nThe `prime` method makes it possible to fetch the best matching result based on the ingoing argument. It will reject data (songs, artists and albums) that contains any of the [these words](https://github.com/oleander/Spot/blob/master/lib/spot/ignore.yml).\n\n``` ruby\nSpot::Search.prime.find_song(\"Sweet Home Alabama\")\n```\n\n### Specify a territory\n\nAll songs in Spotify isn't available everywhere.\nIt might therefore be usefull to specify a location, also know as a *territory*.\n\nIf you for example want to find all songs available in Sweden, then you might do something like this.\n\n```` ruby\nSpot::Search.territory(\"SE\").find_song(\"Sweet Home Alabama\")\n````\n\nYou can find the complete territory list [here](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).\n\n### Filter ingoing arguments\n\nSometimes it may be useful to filer ingoing params.  \nYou can filter the ingoing string by using the `strip` method.\n\n```` ruby\nSpot::Search.strip.find_song(\"3. Who's That Chick ? feat.Rihanna [Singel Version] - (Single)\")\n````\n\nThis is the string that is being passed to Spot.\n\n    \"who's that chick ?\"\n\n### Specify a page\n\n```` ruby\nSpot::Search.page(11).find_song(\"sweet home\")\n````\n\n### Combine methods\n\nYou can easily chain method like this.\n\n```` ruby\nSpot::Search.page(11).territory(\"SE\").prime.strip.find_song(\"sweet home\")\n````\n\n## Data to work with\n\nAs soon as the `result` or `results` method is applied to the query a request to Spotify is made.\n\nHere is an example (`#result`).\n\n    \u003e\u003e song = Spot::Search.find_song(\"sweet home\").result\n    \n    \u003e\u003e puts song.title\n    =\u003e Home Sweet Home\n    \n    \u003e\u003e puts song.class\n    =\u003e Spot::Song\n \nHere is an example (`#results`).\n   \n    \u003e\u003e songs = Spot::Search.find_all_songs(\"sweet home\").results\n    \u003e\u003e puts songs.count\n    =\u003e 100\n\n### Base\n\n`Spot::Song`, `Spot::Artist` and `Spot::Album` shares the following methods.\n\n- **popularity** (*Float*) Popularity acording to Spotify. From `0.0` to `1.0`.\n- **href** (*String*) Url for the specific object.\nDefault is a spotify url on this format: `spotify:track:5DhDGwNXRPHsMApbtVKvFb`.\n`http` may be passed as a string, which will return an Spotify HTTP Url.\n- **available?** (*Boolean*) Takes one argument, a territory. Returns true if the object is accessible in the given region.\nRead more about it in the *Specify a territory* section above.\n- **to_s** (*String*) A string representation of the object.\n- **valid?** (*Boolean*) Returns true if the object is valid, a.k.a is accessible in the given territory. \nIf no territory is given, this will be true.\n- **name** (*String*) Same as `Spot::Song#title`.\n\n### Song\n\nMethods available for the `Spot::Song` class.\n\n- **length** (*Fixnum*) Length in seconds.\n- **title** (*String*) Song title.\n- **to_s** (*String*) String representation of the object in this format: *artist - song*.\n- **artist** (*Artist*) The artist.\n- **album** (*Album*) The album.\n\n### Artist\n\nMethods available for the `Spot::Artist` class.\n\n- **name** (*String*) Name of the artist.\n- **to_s** (*String*) Same as above.\n\n### Album\n\nMethods available for the `Spot::Album` class.\n    \n- **artist** (*Artist*) The artist.\n\n### Spot\n\n```` ruby\nspot = Spot::Search.find_song(\"kaizers orchestra\")\n\nputs spot.num_results # =\u003e 188\nputs spot.limit       # =\u003e 100\nputs spot.offset      # =\u003e 0\nputs spot.query       # =\u003e \"kaizers orchestra\"\n````\n\n- **num_results** (*Fixnum*) The amount of hits.\n- **limit** (*Fixnum*) The amount of results on each page.\n- **query** (*String*) The search param that was passed to Spotify.\n- **offset** (*Fixnum*)\n\n## Request limit!\n\n**Be aware**: Spotify has an request limit set for 10 requests per second.  \nWhich means that you can't just use it like this.\n\n```` ruby\n[\"song1\", \"song2\", ...].each do |song|\n  Spot::Search.find_song(song)\n  # Do something with the data.\nend\n````\n\nInstead use something like [Wire](https://github.com/oleander/Wire) to limit the amount of requests per seconds.\n\n```` ruby\nrequire \"rubygems\"\nrequire \"wire\"\nrequire \"spot\"\n\nwires = []\n[\"song1\", \"song2\" ... ].each do |s|\n  wires \u003c\u003c Wire.new(max: 10, wait: 1, vars: [s]) do |song|\n    Spot::Search.find_song(song)\n    # Do something with the data.\n  end\nend\n\nwires.map(\u0026:join)\n````\n\n## How do install\n\n    [sudo] gem install spot\n\n## Requirements\n\n*Spot* is tested in *OS X 10.6.7, 10.7.4* using Ruby *1.8.7*, *1.9.2*.\n\n## License\n\n*Spot* is released under the *MIT license*.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foleander%2Fspot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foleander%2Fspot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foleander%2Fspot/lists"}