[WS] iTunes source script with multiple search criteria

Greetings to the web sources community.

I'm copying my original post from [General Discussion] to [Development>Web Sources scripts] to faciitate the sharing of my script, and to make it easier to discuss improvements / modifications.


Please note this is NOT a finished product. It's still in development, due to a large oversight on my part.
Details are in this post.


After using pone's WS Itunes script(s) for years, I've finally decided to take up scipting and give a shot
at creating a tool with the functions I wanted. And the main one was create a script that could be
used internationally, i.e. I could somehow define what country the script would query.

This made sense to me, since if there was an artist from a certain country, or if an album had a localized
special edition, I would want to get metadata info from Itunes from that country. There are already WS scripts for several countries, but personally I find them cumbersome. I don't need scripts for 20+ countries if I mainly use just 2 or 3 and seldom use the rest. So that was my starting point.

Instructions:

"Search by:" / [clear]
The "Search by:" box has the following fields:

"Country:" Simply state which country you would like the script to query. Please use correct country codes
or a bad request error will be generated. List of available country codes is available at https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

"Language:" / [clear] / en_us / ja_jp
On the Itunes API page is mentioned the possibility of displaying results from a non-English alphabet (e.g japanese) in English, or displaying search results in japanese charaters from the english alphabet, if provided by the database. For always displaying results in English, the 'language' field must have the value 'en_us'; for always displaying results in japanese, the value must be 'ja_jp'. Leaving the field blank will display the results as is. Other/incorrect values will return a bad request error message

NB: Though the ja_jp option exists and is available, I have never had a query whose results were ported to japanese characters if they were not already the original writing system. Please take note of this if/when using the 'ja_jp' option.

"Query:" / [clear]
Standard query field; script will load artist and album info onto the filed, if said info is already present in the files. Query also loads the itunes' unique album identification code (if available), which dramatically increases search times and displays always correct results, if provided with correct info. Manual input is also available.

This script is intended to be used in tandem with localized versions; as a tool to perform one-off searches of seldom searched countries, instead of having 20+ WS scripts cluttering the Tag Sources menu.

So, please enjoy using this script, as much as I enjoyed making it (and leave a like if you think the script is worth it).

Thank you.


Current release:
- beta version 200191130_0

Known issues:
- [Query field] only supports UTF-8-compatible characters (A-Z, a-z, 0-9). Foreign writing systems (eg. japanese kanji/kana) or special characters (eg. Γ§, Γ©, ΓΆ) will return an invalid url error. Queries in English should be safe, as well as [CollectionId] number queries

iTunes_INTERNATIONAL_beta20191130_0.src (7.0 KB)

Here's some addicional info regarding my script:

- first, this is not a copy of pone's WS scripts. I have used them for many years, and when I decided to try to crete my own script, I used pone scripts to learn the proper commands, and how a search is conducted, as well as a template. But it is my own creation, and I've added some feature I could not find previously (like multiple search fields).

- This is a work in progress, in beta stage. Since I'm trying to create an international iTunes script, the inability to query in foreign writing systems, to call this a finished product would be incorrect.

For any fellow script enthusiast, here is my current problem, with an example:
- Conduct a search in Itunes store- japan, for an album, using the term "γ‚‰γβ˜†γ™γŸ", and list the first 20 results, in english.

The query link would be:
https://itunes.apple.com/search?entity=album&limit=20&lang=en_us&country=jp&term=γ‚‰γβ˜†γ™γŸ

Since the API can't recognize japanese characters, I have to use url-utf-8 encoding, which encodes
"term=γ‚‰γβ˜†γ™γŸ" into "term=%E3%82%89%E3%81%8D%E2%98%86%E3%81%99%E3%81%9F"

In WS script, this would be:
[IndexUrl]=https://itunes.apple.com/search?entity=album&limit=20&lang=en_us&country=jp&term=%s
[SearchBy]=γ‚‰γβ˜†γ™γŸ, or rather
[SearchBy]=%E3%82%89%E3%81%8D%E2%98%86%E3%81%99%E3%81%9F
[Encoding]=url-utf-8

Which works fine. However, in order to have the search parameters as variables, I need:
[IndexUrl]=https://itunes.apple.com/search?entity=album&limit=20%s
[SearchBy]=&lang=en_us&country=jp&term=γ‚‰γβ˜†γ™γŸ
[Encoding]=url-utf-8

which outputs
https://itunes.apple.com/search?entity=album&limit=20%26lang%3Den_us%26country%3Djp%26term%3Dγ‚‰γβ˜†γ™γŸ

And this doesn't work. Because not only "γ‚‰γβ˜†γ™γŸ" value gets converted into URL-UTF-8, but also the "&" and "=" symbols in "&lang=", &country=" and "&term=" which the API can't recognize

I can change the encoding to 'utf-8', but then I'd be back at square one, because "γ‚‰γβ˜†γ™γŸ" isn't recognized.

Any help would be greatly appreciated. Thank you.

Thanks for describing the encoding issue. I've fixed this with Mp3tag v2.99c.

Please also note that you now need to use || as separator at SearchBy as described here

Thank you so very much.
I'm very glad I'm able to help improve Mp3tag.

I do remember the need to use "| |" as separator; I released my script for Mp3tag v2.99a (since it's the current release and the one I believe most users -myself included- have installed) and was planning to update to the "| |" version upon release of version 2.99b from beta to main.

But for development purposes the latest version would be best. I'll modify my script for version 2.99c (if necessary -I've just noticed it had been released), and modify my post accordingly.

Thank you for your reply.

1 Like

Greetings to all.

Finally I was able to put some quality time into scripting, and release the latest version of iTunes WS script international.

Firstly, credits where credits are due. I'd like to thank Florian for taking the time to notice my work, and pointing me in the right direction.
Also, with the release of Mp3Tag 2.99c (beta), the biggest problem afflicting my script has been addressed:

2.99c (2019-12-11)

FIX: multi-field search for tag sources used encoding on whole parameter fragment when building URLs. (#47197 9)

This means that URL-UTF-8 encoding can now be used, which converts foreign characters, therefore making my script usable in any language supported by iTunes API.

List of changes:
> URL-UTF-8 implemented in multi-field search, which now properly converts only the necessary characters in the "Query" field (in version 2.99c)
> Double pipe "| |" used in [SearchBy] for multi-field search;
> [WordSeparator] value changed from "+" to "%20";
> Cleaning up of the code, making it easier to read and understand, and a cleaner debug file (for scripting purposes);
> Minor cosmetic changes to the script.

These changes mean that the current version of the script will only work in Mp3Tag version 2.99c (beta) and above. It will not work in the current (at the time of this post) stable version (2.99a).

On a personal note, it means a lot to me to be able to give back to a progrmam that I've been using for many years.

So, here is iTunes WS script international version. Enjoy.

iTunes_int_INTERNATIONAL_std_lang.src (6.8 KB)

Also, here are the localized versions for the U.S.A. (US), Japan (JP)- in original japanese writing kanji and kana, and a 2nd version for Japan, using converted romaji writing. Since these are the versions I most commonly use, I'm releasing them as well.

iTunes_loc_US_std_lang.src (6.8 KB)
iTunes_loc_JP_std_lang.src (6.8 KB)
iTunes_loc_JP_conv_lang.src (6.8 KB)

Enjoy.