openapi: 3.0.3
info:
  title: MusicBrainz Web Service v2 Areas API
  version: '2.0'
  description: 'The MusicBrainz Web Service v2 is the free public REST API to the MusicBrainz open music encyclopedia,

    operated by the MetaBrainz Foundation (a US 501(c)(3) non-profit).


    The API supports three primary access patterns over twelve core entity types

    (artist, release, release-group, recording, work, label, place, area, event, instrument, series, url, genre):


    - **Lookup** — fetch one entity by its MBID with configurable sub-resource includes.

    - **Browse** — list entities linked to a given parent entity, with pagination.

    - **Search** — full Lucene query syntax across the indexed catalog.


    Non-MBID lookups are available for ISRC (recordings), ISWC (works), DiscID (releases), and URL.


    Responses are returned in MMD-2 XML by default or JSON via the `fmt=json` query parameter.


    The API enforces a strict rate limit of **one request per IP per second** and requires a meaningful

    **User-Agent** header on every request (e.g. `MyApp/1.0.0 ( contact@example.com )`).

    Submission and user-specific endpoints require HTTP Basic or OAuth 2.0 authentication.

    '
  contact:
    name: MetaBrainz Foundation
    url: https://metabrainz.org/
    email: support@metabrainz.org
  license:
    name: API access is free; data licensed CC0 (core) and CC-BY-NC-SA (supplemental)
    url: https://musicbrainz.org/doc/About/Data_License
  termsOfService: https://metabrainz.org/social-contract
  x-generated-from: documentation
  x-last-validated: '2026-05-29'
servers:
- url: https://musicbrainz.org/ws/2
  description: Production MusicBrainz Web Service v2
- url: https://beta.musicbrainz.org/ws/2
  description: Beta MusicBrainz Web Service v2 (pre-release schema changes)
tags:
- name: Areas
  description: Lookup, browse, and search for geographic areas (countries, cities, etc.).
paths:
  /area/{mbid}:
    get:
      operationId: lookupArea
      summary: Lookup Area
      description: Look up a geographic area by MBID.
      tags:
      - Areas
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      parameters:
      - $ref: '#/components/parameters/MBID'
      - $ref: '#/components/parameters/Inc'
      - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Area found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Area'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /area:
    get:
      operationId: searchAreas
      summary: Search Areas
      description: Search areas with a Lucene query.
      tags:
      - Areas
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      parameters:
      - $ref: '#/components/parameters/Query'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Search results
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    MBID:
      name: mbid
      in: path
      required: true
      description: MusicBrainz Identifier (UUID v4) of the entity.
      schema:
        type: string
        format: uuid
        pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
        example: 5b11f4ce-a62d-471e-81fc-a69a8278c7da
    Offset:
      name: offset
      in: query
      required: false
      description: Zero-based offset into the result set for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
    Format:
      name: fmt
      in: query
      required: false
      description: Response serialization format. Defaults to XML; set to `json` for JSON.
      schema:
        type: string
        enum:
        - xml
        - json
        default: xml
    Query:
      name: query
      in: query
      required: true
      description: Lucene-syntax search query string.
      schema:
        type: string
        example: artist:nirvana AND country:US
    Inc:
      name: inc
      in: query
      required: false
      description: Plus-separated list of sub-resources and relationships to include in the response.
      schema:
        type: string
        example: aliases+tags+ratings+artist-rels
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum number of results to return (1-100, default 25).
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
  schemas:
    MBID:
      type: string
      format: uuid
      pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      description: MusicBrainz Identifier (UUID v4) - the canonical primary key for every entity.
      example: 5b11f4ce-a62d-471e-81fc-a69a8278c7da
    Area:
      type: object
      description: A geographic area (country, subdivision, city, etc.).
      properties:
        id:
          $ref: '#/components/schemas/MBID'
        name:
          type: string
          example: United States
        sort-name:
          type: string
        type:
          type: string
          nullable: true
          enum:
          - Country
          - Subdivision
          - County
          - Municipality
          - City
          - District
          - Island
        type-id:
          $ref: '#/components/schemas/MBID'
        iso-3166-1-codes:
          type: array
          items:
            type: string
          example:
          - US
        iso-3166-2-codes:
          type: array
          items:
            type: string
        iso-3166-3-codes:
          type: array
          items:
            type: string
        disambiguation:
          type: string
        life-span:
          $ref: '#/components/schemas/LifeSpan'
    Error:
      type: object
      properties:
        error:
          type: string
        help:
          type: string
    LifeSpan:
      type: object
      description: Begin/end dates and whether the entity has ended.
      properties:
        begin:
          type: string
          description: Begin date (year, year-month, or full ISO date).
          example: 1988-01
        end:
          type: string
          nullable: true
          description: End date (year, year-month, or full ISO date), null if ongoing.
          example: '1994-04-05'
        ended:
          type: boolean
          description: Whether the entity has ended.
  responses:
    NotFound:
      description: Entity not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded - clients must throttle to 1 request per second per IP
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    HTTPBasic:
      type: http
      scheme: basic
      description: HTTP Basic authentication using MusicBrainz editor credentials. Required for submission and user-specific endpoints.
    OAuth2:
      type: oauth2
      description: OAuth 2.0 authentication via the MusicBrainz OAuth server.
      flows:
        authorizationCode:
          authorizationUrl: https://musicbrainz.org/oauth2/authorize
          tokenUrl: https://musicbrainz.org/oauth2/token
          scopes:
            profile: Access user profile
            email: Access user email
            tag: Submit tags
            rating: Submit ratings
            collection: Manage collections
            submit_barcode: Submit release barcodes
            submit_isrc: Submit recording ISRCs