Quick Start

Wanna try our services ? Follow these several steps in order to get your first queries done. Then we'll explain everything in details!

Setup your account

Registration are closed for the moment. Please contact us for any trial.

Register your client

Each request made to our Web API requires to be authenticated by using a specific client. Connect to our portal to create one:

Once submitted, you will receive a unique client_id and client_secret. Please note that those credentials are confidential and that you are responsible for any requests that are made through it. Keep them safely and don't share them with anyone.

Generate an Access Token

Let's now do our first query to generate an Access Token.

curl --location --request POST 'https://api-v2.musimap.io/oauth/access_tokens/client' \
--header 'Content-Type: application/json' \
--data-raw '{
  "client_id": "{YOUR_CLIENT_ID}",
  "client_secret": "{YOUR_CLIENT_SECRET}"
}'

Replace {YOUR_CLIENT_ID} and {YOUR_CLIENT_SECRET} here above and run the command to generate a new token.

{
    "status": 201,
    "timestamp": 1605548750797,
    "data": {
        "id": "232a15c2-2f34-47ef-968b-86c3290d1058",
        "removed_at": null,
        "refreshed_at": null,
        "revoked_at": null,
        "subject_type": "Client",
        "subject_id": "efb3ed15-0052-4e00-9584-1365510b547d",
        "issued_at": 1605548750779,
        "expires_at": 1605555950779,
        "issuer_type": null,
        "issuer_id": null,
        "organization_id": "e4587784-e0a4-43ff-8466-bf17afbb352c",
        "token": "eyJqdGkiOiIyMzJhMTVjMi0yZTM0LTQ3ZWYtOTY4NTItNGUwMC05NTg0LTEzNjU1MTBiNTQ3ZCIsImV4cCI6MTYwNTU1NTk1MCwiaWF0IjoxNjA1NTQ4NzUwfQ==.mWSJ8A6Yz8SMgly4PqOiyP1KSFMJdaQ9fIknKmXHecIomO_HhEk5Ot15LW8AW8cvsKb1Mwk6IGu1ZMSy-hD5w45kbWOcXG1bHveEYmA4k73nCo9Pzx7muPsSD7z8adsfkHQkf2dFc-YDzRSfziu21jO9alrmUPC2UbgvjZy8EZFj2yUzQfKIjYi04NmMzMjkwZDEwNTgiLCJvaWQiOiJlNDU3Nzc4NC1lMGE0LTQyZmYtODQ2Ni1iZjE3YWZiNmI1MmMiLCJzdWIiOiJDbGllbnQ6OmVlYjNlZDE1LTAwtNfKsDn4D9sCIw-97WO6Lf77ENPNu6Vgyl8d4j210kYMqcu8sGvAcpsE-_WVlAyiEi5ZhLMi_5EMcE9gK3h68109yjsceKvM0IxZw3WCnK2-2pMkiCmM27K92w6h2WIQ9XNbo4ibqYtFhOWPcmBZH9LOSOIWlQcwA=="
    }
}

You now have an Access Token that will remain valide for the next 7,200 seconds (2 hours).

Query the lexicology

curl --location --request GET 'https://api-v2.musimap.io/lexicology/tags?limit=2' \
--header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Replace {YOUR_ACCESS_TOKEN} by the one you just generated and run the command to get your first results.

{
    "status": 200,
    "timestamp": 1605550791229,
    "data": [
        {
            "id": "0158d0de-e706-4d42-a727-ee006188c5e1",
            "category": {
                "id": "01d03c9b-1a50-4921-a896-d01372bab5bf",
                "name": "Mood"
            },
            "name": "Soothing"
        },
        {
            "id": "128f1a5d-9589-4be0-8211-45f038de8f40",
            "category": {
                "id": "01d03c9b-1a50-4921-a896-d01372bab5bf",
                "name": "Mood"
            },
            "name": "Determined"
        }
    ],
    "offset": 0,
    "limit": 2,
    "size": 2,
    "total_size": 2881
}

This endpoint features several parameters that you may want to combine:

curl --location --request GET 'https://api-v2.musimap.io/lexicology/tags?limit=2&category_name=Genre&name=Disco' \
--header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

This query will return 2 Genres that contains the string Disco in their name. Note that the response indicates there's 6 tags matching your query.

{
    "status": 200,
    "timestamp": 1605550904910,
    "data": [
        {
            "id": "d004e500-719d-4880-9eec-1e76cabeec11",
            "category": {
                "id": "e2c9567d-7b02-440b-85cc-2411749b08d7",
                "name": "Genre"
            },
            "name": "Disco"
        },
        {
            "id": "4f0f3374-988a-4482-a647-ecc6e5b881d9",
            "category": {
                "id": "e2c9567d-7b02-440b-85cc-2411749b08d7",
                "name": "Genre"
            },
            "name": "Disco Funk"
        }
    ],
    "offset": 0,
    "limit": 2,
    "size": 2,
    "total_size": 6
}

"Et voilà", you now have completed your first interaction with our API. There are a lot more endpoints and parameters to discover, feel free to read our References Guide to learn more about your further options.