Event Art Archive/API: Difference between revisions

From MusicBrainz Wiki
Jump to navigationJump to search
(Created page with "Any requests to fetch event art must go through the eventartarchive.org service. There are 3 classes of end points, text surrounded in braces indicates a variable. ===/event/{mbid}/=== ====Summary==== Fetches a JSON listing of available images for a MusicBrainz event. ====Accepted Methods==== * GET * HEAD ====Responses==== * 307 redirect to an index.json file, if there is an event with this MBID. * 400 if {mbid} cannot be parsed as a valid UUID. * 404 if there is...")
(No difference)

Revision as of 23:32, 25 June 2024

Any requests to fetch event art must go through the eventartarchive.org service. There are 3 classes of end points, text surrounded in braces indicates a variable.

/event/{mbid}/

Summary

Fetches a JSON listing of available images for a MusicBrainz event.

Accepted Methods

  • GET
  • HEAD

Responses

  • 307 redirect to an index.json file, if there is an event with this MBID.
  • 400 if {mbid} cannot be parsed as a valid UUID.
  • 404 if there is no event with this MBID.
  • 405 if the request method is not one of GET or HEAD.
  • 406 if the server is unable to generate a response suitable to the Accept header.
  • 503 if the user has exceeded their rate limit.

Example

   > GET /event/2c85b200-4799-40f6-b6db-6481a2dc4460 HTTP/1.1
   > Host: eventartarchive.org
   > Accept: application/json

   < HTTP/1.0 200 OK
   < Status: 200
   {
      "event": "https://musicbrainz.org/event/2c85b200-4799-40f6-b6db-6481a2dc4460",
      "images": [
         {
            "approved": true,
            "comment": "",
            "edit": 112144836,
            "front": true,
            "id": 38900617320,
            "image": "https://eventartarchive.org/event/2c85b200-4799-40f6-b6db-6481a2dc4460/38900617320.png",
            "thumbnails": {
               "1200": "https://eventartarchive.org/event/2c85b200-4799-40f6-b6db-6481a2dc4460/38900617320-1200.jpg",
               "250": "https://eventartarchive.org/event/2c85b200-4799-40f6-b6db-6481a2dc4460/38900617320-250.jpg",
               "500": "https://eventartarchive.org/event/2c85b200-4799-40f6-b6db-6481a2dc4460/38900617320-500.jpg",
               "large": "https://eventartarchive.org/event/2c85b200-4799-40f6-b6db-6481a2dc4460/38900617320-500.jpg",
               "small": "https://eventartarchive.org/event/2c85b200-4799-40f6-b6db-6481a2dc4460/38900617320-250.jpg"
            },
            "types": ["Poster"]
         }
      ]
   }


/event/{mbid}/front

Summary

Fetches the first poster for the event, if one exists.

Accepted Methods

  • GET
  • HEAD

Responses

  • 307 if a poster is found for this event.
  • 400 if {mbid} cannot be parsed as a valid UUID.
  • 404 if there is either no event with this MBID, or if no poster is found.
  • 405 if the request method is not GET or HEAD.
  • 503 if the user has exceeded their rate limit.

Example

   > GET /event/2c85b200-4799-40f6-b6db-6481a2dc4460/front HTTP/1.1
   > Host: eventartarchive.org

   < HTTP/1.1 307 Temporary Redirect
   < Status: 307
   < Location: https://archive.org/download/mbid-2c85b200-4799-40f6-b6db-6481a2dc4460/mbid-2c85b200-4799-40f6-b6db-6481a2dc4460-38900617320.png

/event/{mbid}/{id}

Summary

Fetches a specific image. The possible {id} values can be found by parsing the response of a /event/{mbid} request.

Accepted methods

  • GET
  • HEAD

Responses

  • 307 redirect to a binary image.
  • 404 if an event with this MBID cannot be found.
  • 405 if the request method is not GET or HEAD.
  • 503 if the user has exceeded their rate limit.

Example

   > GET /event/2c85b200-4799-40f6-b6db-6481a2dc4460/38900617320.png HTTP/1.1
   > Host: eventartarchive.org

   < HTTP/1.1 307 Temporary Redirect
   < Status: 307
   < Location: https://archive.org/download/mbid-2c85b200-4799-40f6-b6db-6481a2dc4460/mbid-2c85b200-4799-40f6-b6db-6481a2dc4460-38900617320.png

/event/{mbid}/({id}|front)-(250|500|1200)

Summary

Fetches a thumbnail for a specific image. The possible {id} values can be found by parsing the response of a /event/{mbid} request. The current supported thumbnail sizes are 250px, 500px, and 1200px.

Accepted methods

  • GET
  • HEAD

Responses

  • 307 redirect to a binary image. This redirected request may resolve to a 404 if the thumbnail does not exist.
  • 404 if an event with this MBID cannot be found.
  • 405 if the request method is not GET or HEAD.
  • 503 if the user has exceeded their rate limit.

Example

   > GET /event/2c85b200-4799-40f6-b6db-6481a2dc4460/38900617320-250.png HTTP/1.1
   > Host: eventartarchive.org

   < HTTP/1.1 307 Temporary Redirect
   < Status: 307
   < Location: https://archive.org/download/mbid-2c85b200-4799-40f6-b6db-6481a2dc4460/mbid-2c85b200-4799-40f6-b6db-6481a2dc4460-38900617320_thumb250.jpg

OPTIONS support

All end points at the eventartarchive.org support the HTTP OPTIONS method, to determine which request methods are valid for each resource. On an OPTIONS request, the server will do no processing, other than returning an empty response with the 'Allow:' header field set to the support methods for that resource. For supported methods, consult the specification of each individual resource.

Rate limiting rules

There are currently no rate limiting rules in place at http://eventartarchive.org.

Event Art Archive Metadata

The Event Art Archive provides a collection of metadata with each event, which allows users to determine what event art can be used for. The metadata will be stored and served as application/json. The metadata consists of a ordered list of entries, where each entry contains:

image
the full eventartarchive.org url to the original image
thumbnails
object containing the keys "250", "500", and "1200" linking to thumbnails of those sizes (in pixels); "small" and "large" are deprecated keys and are equivalent to "250" and "500", respectively
types
list of zero or more types for the image (see the list).
front
boolean, indicates if this is the "main front" (returned by /front)
comment
a free text comment
approved
whether the image was approved by the MusicBrainz edit system
edit
the edit ID on MusicBrainz (e.g. 123)
id
archive.org's internal file ID

The metadata also contains a link to the MusicBrainz event, under the event field.

JSON Output Example

 {
    "images": [
        {
            "types": ["Poster"],
            "front": true,
            "comment": "",
            "image": "http://eventartarchive.org/...jpg",
            "thumbnails": {
                "small": "http://eventartarchive.org/...-250.jpg",
                "large": "http://eventartarchive.org/...-500.jpg"
            },
            "approved": true,
            "edit": 123,
            "id": "456"
        },
        {
            "types": ["Schedule"],
            "front": false,
            "comment": "autographed by ModBot",
            "image": "http://eventartarchive.org/...jpg",
            "thumbnails": {
                "250": "http://eventartarchive.org/...-250.jpg",
                "500": "http://eventartarchive.org/...-500.jpg",
                "1200": "http://eventartarchive.org/...-1200.jpg",
                "small": "http://eventartarchive.org/...-250.jpg",
                "large": "http://eventartarchive.org/...-500.jpg"
            },
            "approved": true,
            "edit": 124,
            "id": "457"
        }
    ],
    "event": "http://musicbrainz.org/event/2ba4396d-c0be-4a56-b4ea-0438306eb3be"
  }

File naming

Files are named using integers derived from the current high resolution system time, for example via the `Time::HiRes::time` function in Perl. The exact formula to create a new file name is: 

   int((time() - 1327528905) * 100)

This filename is allocated by MusicBrainz at the time of upload, and will never change.

Retrieved from "https://wiki.musicbrainz.org/index.php?title=Event_Art_Archive/API&oldid=77793"