Linked Jazz

API Documentation

This document explains the Linked Jazz API which returns data from the project's transcript analysis and crowdsourcing programs. For the Jazz Name Directory, please visit this page.

The Base URL is:

http://linkedjazz.org/api/

This api has three end points that accept GET requests:

• http://linkedjazz.org/api/people/
• http://linkedjazz.org/api/relationships/
• http://linkedjazz.org/api/text/

Data is returned by default in JSON format, some requests allow the return of the data in RDF Triple format if a "/nt" is append to the request url. Likewise, the relationship endpoint will return a GEXF network file for use in Gephi network analysis program if "/gexf" is append to the request (examples provided below).

People

The people endpoint has a search request and a dump endpoint. Entities that are returned appear in the transcripts analyzed and have relationships associated with them. To search add "search/XYZ" to the url. For example to search for people with the word "Fats" in their name use:

http://linkedjazz.org/api/people/search/Fats

Will return a array of objects with names matching the search request.

[
    {
        "name": "Fats Navarro",
        "uri": "<http://dbpedia.org/resource/Fats_Navarro>",
        "uriEncoded": "%3Chttp%3A%2F%2Fdbpedia.org%2Fresource%2FFats_Navarro%3E",
        "image": "http://linkedjazz.org/image/square/Fats_Navarro.png"
    },
        {
        "name": "Fats Waller",
        "uri": "<http://dbpedia.org/resource/Fats_Waller>",
        "uriEncoded": "%3Chttp%3A%2F%2Fdbpedia.org%2Fresource%2FFats_Waller%3E",
        "image": "http://linkedjazz.org/image/square/Fats_Waller.png"
    }
]

• name - The individual's name.
• uri - The authoritative URI used for this individual.
• uriEncoded - The URI encoded for use with this API
• image - Optional, the image we use for this individual.
• comment - Optional, any extra information added for this person by the LJ project.

This API uses the full URI for requests, the URI must be encoded, forward slashes must be represented by %2F

http://linkedjazz.org/api/people/search/Fats/nt

Will return the same information in RDF Triple format.

To download all idividuals at once (data dump) use:

http://linkedjazz.org/api/people/all

Data dumps are updated hourly.

Relationships

Relationship information has two facets:

1. That a basic rel:knowsOf relationship exists and its direction.
2. Annotations from the crowdsourcing tool as to the more specific nature of the relationship.

All annotations are returned for a specific relationship, these annotations are added to the system by visitors to the 52nd St. crowdsourcing tool. Currently the API does not aggregate the varying opinions of a specific relationship into a quantified value, it just returns all opinions (even duplicate). This endpoint has the ability to return Gephi compatible GEXF files by appending "/gexf" to the url. Annotated relationships are not returned in the Gephi network, only a single basic rel:knowsOf. This endpoint can also return triples with the "/nt" argument.

You can request:

• Relationships of an individual
• Request their Ego network
• Data dump of all relationships (updated hourly)

To return all relationships an idividual has pass their encoded URI as the seconf argument:

 http://linkedjazz.org/api/relationships/%3Chttp%3A%2F%2Fdbpedia.org%2Fresource%2FFats_Navarro%3E 

To return their ego network add /ego/:

 http://linkedjazz.org/api/relationships/ego/%3Chttp%3A%2F%2Fdbpedia.org%2Fresource%2FFats_Navarro%3E 

To return all relationships:

 http://linkedjazz.org/api/relationships/all

Again, adding "/nt" or "/gexf" will return the request in that format.

JSON Response:

• transcript - the hash id of the transcript this relationship occured in.
• uri - the uri of the other person invovled in this relationship
• uriEncoded - the encoded uri of the other person invovled in this relationship
• count - the number of times this relationship happend in this transcript
• occurances - and array of objects:
  • id - the id of the text fragment
  • type - A or Q, answer or question type of the fragment
• isTalkingAbout - true or false, if true the person owning this response (the uri used in the request) is talking about this person. Otherwise This person is talking about the person used in the request.
• userTalkingAbout/userBeingTalkedAbout - an array of data from the crowdsourcing, each object contains:
  • id - internal id
  • source - who is talking
  • target - about whom
  • transcript - the id of the transcript it occured in
  • value - The RDF statement of the opinion the user had of this realtionship:
    • http://purl.org/vocab/relationship/knowsOf
    • http://purl.org/vocab/relationship/hasMet
    • http://purl.org/vocab/relationship/acquaintanceOf
    • http://purl.org/vocab/relationship/friendOf
    • http://purl.org/vocab/relationship/closeFriendOf
    • http://purl.org/vocab/relationship/influencedBy
    • http://purl.org/vocab/relationship/mentorOf
    • http://purl.org/ontology/mo/collaborated_with
    • http://linkedjazz.org/ontology/inBandTogether
    • http://linkedjazz.org/ontology/playedTogether
    • http://linkedjazz.org/ontology/bandmember
    • http://linkedjazz.org/ontology/touredWith
    • http://linkedjazz.org/ontology/bandLeaderOf
  • idLocals - the pair of text fragment ids for this judgement.
  • sourceEncoded/targetEncoded - the uris encoded

Text

The text endpoint simply returns text from the transcript, pass it the transcript hash ID along with the localId numbers you want seperated by commas. This informaton is returned in the realtionship calls. For example:

 http://linkedjazz.org/api/text/f3f0c653ce34f6ff5b6c11734cbe154a/1,5,6,7,4,3

Only JSON response for the text endpoint are available.

100 Examples