Developer API documentation

ID Schemas

Data for entities can be requested using Semetric UUIDs or a number of third-party IDs.

To request data for an entity using a third-party ID, this should be prefixed with the id type as follows:

http://api.semetric.com/[entity_type]/[idtype]:[id]/[dataset]?[arguments]

Currently the valid ID prefixes include:

  • facebook
  • freebase
  • imdb
  • instagram
  • lastfm
  • musicmetric (old integer artist IDs)
  • musicbrainz
  • myspace
  • songkick
  • soundcloud
  • spotify
  • twitter
  • vevo
  • wikipedia

Examples

The following are all equivalent ways (not exhaustive) to refer to the artist Ladytron:

  • Semetric UUID:

    32e628734a6a4100834a05032a909813

  • musicbrainz ID:

    musicbrainz:b45335d1-5219-4262-a44d-936aa36eeaed

  • last.fm artist name:

    lastfm:ladytron

  • songkick artist name:

    songkick:16865

  • twitter artist id:

    twitter:29797333

The following examples give equivalent results using different ID schemes, and retrieve basic information from the API including the Semetric UUID and entity name, in this case the band Ladytron:

http://api.semetric.com/entity/32e628734a6a4100834a05032a909813?token=[api_key] http://api.semetric.com/entity/twitter:29797333?token=[api_key] http://api.semetric.com/entity/lastfm:ladytron?token=[api_key]

The response is:

{
  "success": true
  "response":
  {
    "id": "32e628734a6a4100834a05032a909813",
    "name": "Ladytron"
  },
}

If the ID doesn’t exist or our system doesn’t know about it this will generate a JSON response with a 404 error code. For example:

http://api.semetric.com/artist/lastfm:this+is+made+up?token=[api_key]

returns the following error:

{
  "success": false,
  "error":
  {
    "msg": "This resource could not be found",
    "code": 404
  }
}