> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Music Genre Groups

> Retrieve a list of high-level music genre groups for categorizing and filtering music

## Overview

Retrieve a list of high-level music genre groups that categorize the more specific genres into broader musical families. Use these genre groups to provide simplified filtering options or to organize genres hierarchically in your application.

<Note>
  You need a valid API key to use this endpoint. Get your API key from the [API Access page](https://app.pictory.ai/api-access) in your Pictory dashboard.
</Note>

***

## API Endpoint

```http theme={null}
GET https://api.pictory.ai/pictoryapis/v1/music/genres/groups
```

***

## Request Parameters

### Headers

<ParamField header="Authorization" type="string" required>
  API key for authentication (starts with `pictai_`)

  ```
  Authorization: YOUR_API_KEY
  ```
</ParamField>

***

## Response

<ResponseField name="genreGroups" type="array of strings">
  Array of high-level music genre group names. Each group represents a broad musical category that encompasses multiple specific genres.
</ResponseField>

***

## Response Examples

<ResponseExample>
  ```json 200 - Success theme={null}
  [
    "Cinematic",
    "Hip Hop",
    "Electronic",
    "Blues & Jazz",
    "Folk",
    "Rock",
    "Country",
    "Dance",
    "World",
    "Orchestral",
    "R&B & Soul",
    "Pop"
  ]
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "message": "Unauthorized"
  }
  ```
</ResponseExample>

***

## Code Examples

<Tip>
  Replace `YOUR_API_KEY` with your actual API key that starts with `pictai_`
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.pictory.ai/pictoryapis/v1/music/genres/groups \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'accept: application/json' | python -m json.tool
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.pictory.ai/pictoryapis/v1/music/genres/groups"
  headers = {
      "Authorization": "YOUR_API_KEY",
      "accept": "application/json"
  }

  response = requests.get(url, headers=headers)
  genre_groups = response.json()

  # Print all available genre groups
  for group in genre_groups:
      print(group)
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.pictory.ai/pictoryapis/v1/music/genres/groups',
    {
      method: 'GET',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'accept': 'application/json'
      }
    }
  );

  const genreGroups = await response.json();
  console.log('Available genre groups:', genreGroups);
  ```
</CodeGroup>

## Usage Notes

<Tip>
  Genre groups provide a simplified way to categorize music by broad styles. Use them to create top-level navigation or filtering, then combine with the specific genres endpoint for detailed selection.
</Tip>

<Note>
  **Hierarchical Organization**: These 12 genre groups encompass the 100+ specific genres available through the `/music/genres` endpoint, providing a logical hierarchy for music organization.
</Note>

## Common Use Cases

### 1. Create Hierarchical Genre Navigation

Build a two-level genre selection interface with groups and specific genres:

```python theme={null}
import requests

headers = {"Authorization": "YOUR_API_KEY"}

# Get genre groups
groups = requests.get(
    "https://api.pictory.ai/pictoryapis/v1/music/genres/groups",
    headers=headers
).json()

# Get all specific genres
all_genres = requests.get(
    "https://api.pictory.ai/pictoryapis/v1/music/genres",
    headers=headers
).json()

# Create hierarchical structure
genre_hierarchy = {
    "Rock": [g for g in all_genres if 'Rock' in g and 'Folk' not in g],
    "Electronic": [g for g in all_genres if any(x in g for x in ['Electronic', 'House', 'Techno', 'Trance'])],
    "Blues & Jazz": [g for g in all_genres if 'Jazz' in g or 'Blues' in g],
    # ... continue for other groups
}
```

### 2. Populate Multi-Level Dropdown

Create a grouped dropdown selector for better user experience:

```javascript theme={null}
const response = await fetch(
  'https://api.pictory.ai/pictoryapis/v1/music/genres/groups',
  { headers: { 'Authorization': 'YOUR_API_KEY' } }
);
const genreGroups = await response.json();

// Create optgroup structure for HTML select
const genreGroupOptions = genreGroups.map(group => ({
  label: group,
  value: group,
  type: 'group'
}));

// Use in HTML
/*
<select>
  <optgroup label="Cinematic">
    <option>Film Score (Orchestral)</option>
    <option>Film Score (Electronic)</option>
    <option>Horror</option>
  </optgroup>
  <optgroup label="Rock">
    <option>Classic Rock</option>
    <option>Indie Rock</option>
    ...
  </optgroup>
</select>
*/
```

### 3. Filter Music by Broad Category

Allow users to quickly filter music by general style before refining:

```python theme={null}
def get_music_by_genre_group(group_name, api_key):
    """
    Get all specific genres within a genre group
    """
    headers = {"Authorization": api_key}

    # Get all genres
    all_genres = requests.get(
        "https://api.pictory.ai/pictoryapis/v1/music/genres",
        headers=headers
    ).json()

    # Map groups to their genres
    group_mapping = {
        "Rock": lambda g: 'Rock' in g and 'Folk' not in g,
        "Electronic": lambda g: any(x in g for x in ['Electronic', 'House', 'Techno', 'Trance', 'Dubstep']),
        "Blues & Jazz": lambda g: 'Jazz' in g or 'Blues' in g,
        "Hip Hop": lambda g: 'Hip Hop' in g or g in ['Trap', 'Gangsta', 'Drill'],
        "World": lambda g: any(x in g for x in ['African', 'Asian', 'Brazilian', 'Cuban', 'Indian']),
        # ... other mappings
    }

    if group_name in group_mapping:
        return [g for g in all_genres if group_mapping[group_name](g)]
    return []

# Example usage
rock_genres = get_music_by_genre_group("Rock", "YOUR_API_KEY")
print(f"Rock genres: {rock_genres}")
```

### 4. Build Genre Explorer UI

Create an interactive genre exploration interface:

```javascript theme={null}
async function buildGenreExplorer() {
  const response = await fetch(
    'https://api.pictory.ai/pictoryapis/v1/music/genres/groups',
    { headers: { 'Authorization': 'YOUR_API_KEY' } }
  );
  const groups = await response.json();

  // Create tabs for each genre group
  const genreExplorer = groups.map(group => ({
    groupName: group,
    displayName: group,
    icon: getIconForGroup(group), // Custom function to assign icons
    color: getColorForGroup(group) // Custom function for color coding
  }));

  return genreExplorer;
}

function getIconForGroup(group) {
  const icons = {
    'Cinematic': '🎬',
    'Hip Hop': '🎤',
    'Electronic': '🎹',
    'Blues & Jazz': '🎷',
    'Rock': '🎸',
    'Orchestral': '🎻',
    'Pop': '🎵',
    'World': '🌍'
  };
  return icons[group] || '🎶';
}
```

### 5. Validate and Map User Selections

Ensure user selections map correctly to genre groups:

```python theme={null}
import requests

def validate_genre_group(user_selection, api_key):
    """
    Validate if a user's selection is a valid genre group
    """
    headers = {"Authorization": api_key}

    valid_groups = requests.get(
        "https://api.pictory.ai/pictoryapis/v1/music/genres/groups",
        headers=headers
    ).json()

    if user_selection in valid_groups:
        return True, f"Valid group: {user_selection}"
    else:
        return False, f"Invalid group. Choose from: {', '.join(valid_groups)}"

# Example
is_valid, message = validate_genre_group("Rock", "YOUR_API_KEY")
print(message)
```

## Genre Group Descriptions

Here's what each genre group typically encompasses:

* **Cinematic**: Film scores, dramatic compositions, and soundtrack-style music
* **Hip Hop**: Rap, trap, gangsta, and hip hop variations
* **Electronic**: House, techno, trance, dubstep, and electronic dance music
* **Blues & Jazz**: All jazz styles, blues variations, and related genres
* **Folk**: Folk music, singer-songwriter, and acoustic styles
* **Rock**: All rock subgenres from classic to alternative
* **Country**: Country music, bluegrass, and Americana
* **Dance**: Upbeat dance music, disco, and club-oriented tracks
* **World**: International and ethnic music from various cultures
* **Orchestral**: Classical, symphonic, and orchestral compositions
* **R\&B & Soul**: Rhythm and blues, soul, and related urban music
* **Pop**: Popular music, contemporary hits, and pop variations