This is documentation for version 20131025 which is deprecated. The current version is 20220401. We will continue to make deprecated versions available to customers who still use them, but new customers should use the latest version.

Getting started

Signing up and making your first calls to OneMusicAPI.

Welcome to the "Getting started" guide to OneMusicAPI. In this guide you'll learn:

To get started with OneMusicAPI, you must first have an API key. Before you can do anything else, you must sign up to the OneMusicAPI service, activate your account and the API key will be viewable in the OneMusicAPI developer portal. Once you have this key, you can begin making calls to OneMusicAPI.

Signing up

Sign-ups are handled at the OneMusicAPI developer portal:

OneMusicAPI developer portal

Click signup to access OneMusicAPI. You'll see the Signup page:

OneMusicAPI developer portal signup page

Enter your information. Your Username will be used to log into the OneMusicAPI developer portal. Your Organization/Group Name is a way of grouping multiple applications, should you have them. Choose a company name, or your own name if this is a personal project.

Click Sign up to send your details to OneMusicAPI. Now check your email; a confirmation email should've arrived in which is a link to activate the account. Once you click that you'll see a message confirming your registration and a login form to sign into your OneMusicAPI account:

OneMusicAPI developer portal login page

Once you are logged in you can click Dashboard to review your API access details, change your plan and view your access statistics. Importantly, you need to find your API key. Click API Access Details:

API access details in the OneMusicAPI developer portal

Under the API key heading is your key. Copy and paste it... we'll need it later.

Hello... OneMusicAPI!

Once you've got your API key you can use a browser or any HTTP client to make a simple query to OneMusicAPI. Here it comes...

http://api.onemusicapi.com/20131025/release?title=Doolittle&artist=Pixies&user_key=8e7ab677802719c540a6311f17b4a357&inc=images&maxResultCount=1

Notice I didn't hyperlink that URL, and for good reason. The API key in the user_key parameter is made up, and won't work.

So, copy and paste that URL, and then paste your own API key in. You should get something like:

[
  {
    "title": "Doolittle",
    "artist": "Pixies",
    "year": "1989",
    "genre": "Alternative rock",
    "media": [
      {
        "tracks": [
          {
            "title": "Debaser",
            "number": "1"
          },
          {
            "title": "Tame",
            "number": "2"
          },
          {
            "title": "Wave of Mutilation",
            "number": "3"
          },
          {
            "title": "I Bleed",
            "number": "4"
          },
          {
            "title": "Here Comes Your Man",
            "number": "5"
          },
          {
            "title": "Dead",
            "number": "6"
          },
          {
            "title": "Monkey Gone to Heaven",
            "number": "7"
          },
          {
            "title": "Mr. Grieves",
            "number": "8"
          },
          {
            "title": "Crackity Jones",
            "number": "9"
          },
          {
            "title": "La La Love You",
            "number": "10"
          },
          {
            "title": "No. 13 Baby",
            "number": "11"
          },
          {
            "title": "There Goes My Gun",
            "number": "12"
          },
          {
            "title": "Hey",
            "number": "13"
          },
          {
            "title": "Silver",
            "number": "14"
          },
          {
            "title": "Gouge Away",
            "number": "15"
          }
        ]
      }
    ],    
    "images": [
      {
        "url": "http://upload.wikimedia.org/wikipedia/en/6/6b/Pixies-Doolittle.jpg",
        "width": "350",
        "height": "370"
      }
    ],
    "score": 1
  }
]

It looks like the album art for Doolittle by the Pixies was returned. So, what happened?

The title and artist parameters determine the release that is being queried. The inc parameter determines what data should be returned (in this case, just the images). Finally the maxResultCount parameter states how many results should be returned.

That's it for the basic tutorial. Your next step is to review the API docs to further customise your queries.

comments powered by Disqus
© 2012-2024 elsten software limited, Unit 4934, PO Box 6945, London, W1A 6US, UK | terms and conditions | privacy policy