:snake: A simple library to fetch data from the iTunes Store API made for Python >= 3.5

Overview

itunespy PyPI version

itunespy is a simple library to fetch data from the iTunes Store API made for Python 3.5 and beyond.

Important: Since version 1.6 itunespy no longer supports versions below Python 3.5. You can still use any previous versions but those won't get any further updates or features.

Installing

You can install it from pip:

pip install itunespy

Or you can simply clone this project anywhere in your computer:

git clone https://github.com/sleepyfran/itunespy.git

And then enter the cloned repo and execute:

python setup.py install

Dependencies

itunespy requires Requests and pycountry installed.

Examples and information

Search an artist and show all its album's names:

import itunespy

artist = itunespy.search_artist('Steven Wilson')  # Returns a list
albums = artist[0].get_albums()  # Get albums from the first result

for album in albums:
    print(album.collection_name)

Or search an album and show all its song's names and length, and finally the album length:

import itunespy

album = itunespy.search_album('One Hour By The Concrete Lake')  # Returns a list
tracks = album[0].get_tracks()  # Get tracks from the first result

for track in tracks:
    print(track.artist_name + ': ' + track.track_name + str(track.get_track_time_minutes()))
print('Total playing time: ' + str(album[0].get_album_time()))

Or search for a track:

import itunespy

track = itunespy.search_track('Iter Impius')  # Returns a list
print(track[0].artist_name + ': ' + track[0].track_name + ' | Length: ' + str(track[0].get_track_time_minutes())) # Get info from the first result

Or ebook authors:

import itunespy

author = itunespy.search_book_author('Fyodor Dostoevsky')  # Search for Dostoevsky

books = author[0].get_books()  # Get books from the firs result

for book in books:
    print(book.track_name)  # Show each book's name

Or software:

import itunespy

telegram = itunespy.search_software('Telegram')

print(telegram[0].track_name)  # Prints 'Telegram Messenger'

Basically, every search_ method is just an alias for a general search with certain parameters to make your life easier.

I made the basic ones, if you miss any, make an issue and provide information about the type you want added.

You can also perform a lookup:

import itunespy

lookup = itunespy.lookup(upc=720642462928) # Lookup for the Weezer's album 'Weezer'

for item in lookup:
    print(item.artist_name + ': ' + item.collection_name)

Since every search or lookup can return more than one object type, every object in the returned list has a 'type' property, so you can check if it's an artist, album or track like this:

import itunespy

lookup = itunespy.lookup(id=428011728)  # Steven Wilson's ID

for l in lookup:
    if l.type == 'artist':
        print('Artist!')
        print(l.artist_type)  # Since it's an artist, you can also check its artist type

For a complete list, take a look at the wrapperType and kind documentation in the iTunes API's site.

Each request has some parameters that you need to know. Searches has these:

term: The URL-encoded text string you want to search for. Example: Steven Wilson.
        The function will take care of spaces so you don't have to.
country: The two-letter country code for the store you want to search.
        For a full list of the codes: http://en.wikipedia.org/wiki/%20ISO_3166-1_alpha-2
media: The media type you want to search for. Since this module is made for music I recommend leaving it blank.
entity: The type of results you want returned, relative to the specified media type. Example: musicArtist.
        Full list: musicArtist, musicTrack, album, musicVideo, mix, song
attribute: The attribute you want to search for in the stores, relative to the specified media type.
limit: The number of search results you want the iTunes Store to return.

Note: Only the term is obligatory, the other ones have default values that will be used in case you don't provide any. Note 2: In specific searches, like search_artist or search_album, etc, don't change entity, since it's configured inside the function to retrieve an specific entity.

For lookups, the same parameters apply except for term, which changes to a couple of id fields:

id: iTunes ID of the artist/album/track
artist_amg_id: All Music Guide ID of the artist
upc: UPCs/EANs

Every search and lookup will always return a list of result_item instances, except if it's an artist, album, movie artist or an ebook author, which inheritates from result_item but has extra methods, like get_albums in music_artist. Each object has their own variables, following the iTunes API names adapted to Python syntax.

To take a look at all of this simply go to the item_result class.

Contributing

I'm accepting any pull request to improve or fix anything in the library, just fork the project and hack it!

Comments
  • [Feature Request] Add a setter method for track_time

    [Feature Request] Add a setter method for track_time

    Hey there, thanks for the nice project!

    I am the developer of ytmdl and my project has been dependent on your library since the beginning.

    It was later that I noticed that the track_time property of the songs are returned in miliseconds, however, my requirement was to get them in seconds, so I added a bit of code that updates the track_time value and then passed the whole results container along.

    It was working all nice and well until the last release. You made the move to change track_time to a property and it turns out the property doesn't have a setter method which is why my code was unable to update the track_time value and so as a result a lot of users started facing the issue.

    However, a few days ago a fellow user pointed out the issue to me and I found out about the latest release that broke my code.

    I just wanted to request to please add a setter method for the track_time property so that I can go back to using all the latest releases as currently I have forced the version 1.5.5 in the setup.

    Cheers! Thanks for the awesome library, really appreciate it.

    enhancement 
    opened by deepjyoti30 5
  • Possible to to download movies ?

    Possible to to download movies ?

    is it possible to download movies that i bought with python and sync it with the library ? iTunes produce horrible speeds ..i tried with IDM but that don't work bcs i can't play the file maybe library sync issue .

    question 
    opened by dualriposte 3
  • Add country support for sub-queries

    Add country support for sub-queries

    When searching the iTunes API it is possible to specify a country. This way one might get a MusicAlgum from the _get_result_list method. Using the get_tracks method on such an album will lookup the album. This however does not retain the country that was initially specified. For albums that are not available on the default (US) iTunes Store this causes get_tracks to effectively fail (no results are returned).

    This pull request adds the country field to ResultItem and retains the country from a search or lookup operation in the respective results. It also modifies the get_tracks method to lookup tracks in the same country that the MusicAlbum belongs to.

    opened by codello 2
  • Way to search by ISRC?

    Way to search by ISRC?

    I'm using the Spotify and iTunes API together and need a way to guarantee the results returned from each are the same. I haven't found a way to search by ISRC with your wrapper but maybe I missed something.

    question 
    opened by kylesurowiec 2
  • taking song that not matches the given id

    taking song that not matches the given id

    This is the code I used to search the specific song. I couldn't figure out where the error would be in the itunespy code .

    import itunespy
    
    
    def main():
        #working song
        #broken arrows avici https://music.apple.com/us/album/stories/1440834059
        #id_number = '1440834528'
    
        #tragic the kid laroy https://music.apple.com/gb/album/tragic-feat-youngboy-never-broke-again-internet-money/1538646756?i=1538647031
        id_number = '1538647031'
        #actiall id itunespy looks up 341728831
    
        track_info = itunespy.lookup(id=id_number)
        album_info = itunespy.lookup(id=track_info[0].collectionId)
    
        track = itunespy.search_track('arrows')
        print(track[0].artist_name + ': ' + track[0].track_name + ' | Length: ' + str(
            track[0].get_track_time_minutes()))  # Get info from the first result
    
    if __name__ == '__main__':
        main()
    
    opened by JensDeLeersnyderPXL 1
  • Asynchronous version

    Asynchronous version

    Hi would it be possible to make an async version with aiohttp? I would modify it myself but I'm fairly new to python so if it's something you're willing to do I'd be grateful. Otherwise if you could point me in the right direction that'd be good too.

    opened by describe19 1
  • Type hints and more

    Type hints and more

    This pull request includes a number of things:

    • Type annotations for every function
    • URL escaping via urllib.parse. This has the following implications:
      • Simpler Code
      • Fixes a bug where if only the artist_amg_id or only the ups was specified for a lookup operation the function would raise an error.
      • Fixes a bug where special characters in search term or other query parameters would not be properly escaped.
    • Dynamic property access in ResultItem this makes it easier to support any new attributes added to the iTunes Search API. Known attributes are included as type hints to help type checkers and IDEs.
    • A new Artist class that is made the superclass of all artist types. The main purpose of this is to provide a more intuitive way to type hint any artist (which is needed search_director for example).
    • The __repr__ function now returns the underlying JSON object of a ResultItem.
    • A Github Actions Workflow that checks the consistency of type annotations via MyPy.
    • Drop support for Python 3.4

    I did try to make all of the changes backwards compatible. The following functions may behave slightly differently:

    • Performing lookups and searches does not raise an error anymore if the artist_amg_id or ups is not a str (at least in some cases). I consider this a bugfix.
    • collection_type, artist_type and track_type are now available in a ResultItem even if it does not have a wrapperType. This is to provide a more consistent interface allowing to query arbitrary fields in a result.
    • The __repr__ function of ResultItems now returns a different value.
    opened by codello 1
  • Documentation Clarification

    Documentation Clarification

    hi in your code file, it states a string to be passed... but in your README.md you use an integer...

    Could you please clarify which value type?

    --------

    def lookup(id=None, artist_amg_id=None, upc=None, country='US', media='all', entity=None, attribute=None, limit=50): """ Returns the result of the lookup of the specified id, artist_amg_id or upc in an array of result_item(s) :param id: String. iTunes ID of the artist, album, track, ebook or software :param artist_amg_id: String. All Music Guide ID of the artist :param upc: String. UPCs/EANs :param country: String. The two-letter country code for the store you want to search. For a full list of the codes: http://en.wikipedia.org/wiki/%20ISO_3166-1_alpha-2 :param media: String. The media type you want to search for. Example: music :param entity: String. The type of results you want returned, relative to the specified media type. Example: musicArtist. Full list: musicArtist, musicTrack, album, musicVideo, mix, song :param attribute: String. The attribute you want to search for in the stores, relative to the specified media type. :param limit: Integer. The number of search results you want the iTunes Store to return. :return: An array of result_item(s) """

    question 
    opened by jasonkolodziej 1
Releases(1.6)
  • 1.6(May 13, 2020)

    Thanks to the wonderful @codello who did all the amazing work on this release! 👍


    • 🔥 Breaking: This version and further versions of itunespy will NOT support any Python version below 3.5. If you need to use this library in any other version you can use itunespy <= 1.5.5 but those won't get any support or new features.
    • 🔥 Breaking: __repr__ now returns a different value (see below) so make sure you don't use this in a non-compatible way before updating.

    • 😄 Type hints are now available throughout the code
    • 😄 collection_type, artist_type and track_type are now available in a ResultItem even if it does not have a wrapperType. This is to provide a more consistent interface allowing to query arbitrary fields in a result.
    • 😄 __repr__ now returns the underlying JSON object of a ResultItem.
    • 😄 ResultItem now has a get_country() method for converting between country code formats via pycountry.
    • 🐛 The country specified in a query is now preserved in any sub-query. Example: Specifying a country via search_artist will now retain that same country when doing a get_albums.
    • 🐛 Performing lookups and searches does not raise an error anymore if the artist_amg_id or ups is not a str.
    • 🐛 Fixed cases in which special characters in search terms or other query parameters would not be properly escaped.
    Source code(tar.gz)
    Source code(zip)
  • 1.5.5(Oct 7, 2015)

  • v1.5(Sep 2, 2015)

    • 😄 Now you can get a Track time in minutes and hours using get_track_time_minutes() and get_track_time_hours()
    • 😄 The function get_tracks() in MusicAlbum now stores all tracks in _track_list if it's empty
    • 😄 You can also get the full playing time of an album using get_album_time()
    • 😄 search_director and search_movie implemented
    Source code(tar.gz)
    Source code(zip)
  • v1.3(Aug 23, 2015)

    • 🔥 Breaking: This new release deprecates the use of artist_genre_name and artist_genre_id in favor of primary_genre_name and primary_genre_id since those properties can be in artists, albums, tracks and more.
    Source code(tar.gz)
    Source code(zip)
Owner
Fran González
Music, code, repeat.
Fran González
Auxiliator is telegram bot for basic web-application analysis

Auxiliator Auxiliator is telegram bot for basic web-application analysis What for? Sometimes there is no access to your main PC, where you can scan we

Revoltage 13 Dec 26, 2021
Project to list all resources in an AWS account with tags.

AWS-ListAll Project to list all resources in an AWS account with tags. This script works on any system Get started: Install python3 and pip3 along wit

Connor Shubham Verlekar 3 Jan 30, 2022
Pure Python implementation of the Windows API method IDvdInfo2::GetDiscID.

pydvdid-m Pure Python implementation of the Windows API method IDvdInfo2::GetDiscID. This is a modification of sjwood's pydvdid. The Windows API metho

4 Nov 22, 2022
Tomli is a Python library for parsing TOML. Tomli is fully compatible with TOML v1.0.0.

Tomli A lil' TOML parser Table of Contents generated with mdformat-toc Intro Installation Usage Parse a TOML string Parse a TOML file Handle invalid T

Taneli Hukkinen 313 Dec 26, 2022
Faux is a chatbot bridge between urbit and discord.

Faux Faux is a chatbot bridge between urbit and discord. Whenever a member posts in your discord group, a bot will echo their message in your urbit gr

10 Dec 27, 2022
A chatbot that helps you set price alerts for your amazon products.

Amazon Price Alert Bot Description A Telegram chatbot that helps you set price alerts for amazon products. The bot checks the price of your watchliste

Rittik Basu 24 Dec 29, 2022
Weather_besac is a French twitter bot that tweet the weather of the city of Besançon in Franche-Comté in France every day at 8am and 4pm.

Weather Bot Besac Weather_besac is a French twitter bot that tweet the weather of the city of Besançon in Franche-Comté in France every day at 8am and

Rgld_ 1 Nov 15, 2021
SMAM2 is a package manager built specifically for SourceMod.

SourceMod Addon Manager 2 (SMAM2) SMAM2 is a package manager built specifically for SourceMod. This was heavily inspired by Phil25's SMAM. I thought t

John Mascagni 6 Sep 16, 2022
Verkehrsunfälle in Deutschland, aufgeschlüsselt nach Verkehrsmittel des Hauptverursachers und Nebenverursachers

How-To Einfach ./main.py ausführen mit der Statistik-Datei aus dem Ordner "Unfälle_mit_mehreren_Beteiligten" als erstem Argument. Requirements python,

4 Oct 12, 2022
Discord Token Creator 🥵

Discord Token Creator 🥵

dropout 304 Jan 03, 2023
Discord Unverified Token Gen

Discord-Unverified-Token-Gen This is a token gen that was made in an hour and just generates unverified tokens, most will be locked. Usage: in cmd jus

Aran 2 Oct 23, 2022
Bot made with Microsoft Azure' cloud service

IttenWearBot Autori: Antonio Zizzari Simone Giglio IttenWearBot è un bot intelligente dotato di sofisticate tecniche di machile learning che aiuta gli

Antonio Zizzari 1 Jan 24, 2022
52pojie 吾爱破解论坛 签到 支持云函数/服务器等Py3环境运行

52pojie-Checkin 52pojie 吾爱破解论坛 签到 Py3单程序 支持云函数/服务器等Py3环境运行 只需要Cookie即可运行 新版说明 依赖包请用项目 https://github.com/BlueSkyXN/requirements-serverless 需要填写的参数有 co

BlueSkyXN 22 Sep 15, 2022
Go-cqhttp Plugin for EFB QQ Slave.

efb-qq-plugin-go-cqhttp efb-qq-plugin-go-cqhttp 是 efb-qq-slave 的插件,需要配合 efb-qq-slave 使用,使用前请先阅读 efb-qq-slave 的文档。

XYenon 26 Dec 11, 2022
Client library for accessing IQM quantum computers

IQM Client Client-side library for connecting to an IQM quantum computer. Installation IQM client is not intended to be used directly by human users.

IQM 10 Dec 21, 2022
Easily update resume to naukri with one click

NAUKRI RESUME AUTO UPDATER I am using poetry for dependencies. you can check or change in data.txt file for username and password Resume file must be

Rahul.p 1 May 02, 2022
Invites link generator for telegram(made for channel referral links)

InviteLinkGen Invites link generator for telegram(for channel referral links) made for @HelakuruEsana channel Spotify Giveaway

Jaindu Charindith 7 Feb 01, 2022
Python: Asynchronous client for the Open-Meteo API.

Python: Asynchronous client for the Open-Meteo API. Asynchronous client for the Open-Meteo API. About Open-Meteo offers free weather forecast APIs for

Franck Nijhof 11 Dec 21, 2022
可基于【腾讯云函数】/【GitHub Actions】/【Docker】的每日签到脚本(支持多账号使用)签到列表: |爱奇艺|全民K歌|腾讯视频|有道云笔记|网易云音乐|一加手机社区官方论坛|百度贴吧|Bilibili|V2EX|咔叽网单|什么值得买|AcFun|天翼云盘|WPS|吾爱破解|芒果TV|联通营业厅|Fa米家|小米运动|百度搜索资源平台|每日天气预报|每日一句|哔咔漫画|和彩云|智友邦|微博|CSDN|王者营地|

每日签到集合 基于【腾讯云函数】/【GitHub Actions】/【Docker】的每日签到脚本 支持多账号使用 特别声明: 本仓库发布的脚本及其中涉及的任何解锁和解密分析脚本,仅用于测试和学习研究,禁止用于商业用途,不能保证其合法性,准确性,完整性和有效性,请根据情况自行判断。

87 Nov 12, 2022