docs.genius.comGenius API

NAV Manage Clients Support Forum TOS Getting Started These Docs are a Genius App Interactively explore API endpoints by connecting your Genius account to this page. Learn how your app can access Genius’s content and community this easily too! Authorize With Genius You’ve linked your Genius account with this site. You’re on your way to building something great! Add Genius Annotations To Your Own Site In addition to interacting with Genius annotations through the API, it’s easy to make any page annotatable and display annotations you’ve created on it. Just add the script tag: script src="https://genius.codes"/script Registering Your Application First, visit the Genius API Client management page and create an API client for your application. This will provide you with a client_id and a client_secret that you’ll use to identify your application to Genius. The redirect_uri is used for authenticating Genius users with your application. You can change it later. The API Client will belong to the user account signed in to Genius when it’s created. Making Requests The available endpoints are listed below in the resources section, along with embedded examples showing how they work and what they return. Genius uses OAuth2 for authentication. All API requests must be authenticated. There are plenty of libraries available to help with this part of your integration. There’s also a detailed guide below if you’re committed to implementing it yourself. Clojure clauth Cocoa & Cocoa Touch OAuth2Client Go OAuth2 for Go Haskell hoauth2 Java Apache Oltu scribe-java JavaScript simple-oauth2 Passport PHP PHP-OAuth2 Python rauth sanction .Net Owin Qt/C++ O2 Ruby OmniAuth intridea/oauth2 Faraday + Faraday Middleware Scala play-silhouette Resources Annotations An annotation is a piece of content about a part of a document. The document may be a song (hosted on Genius) or a web page (hosted anywhere). The part of a document that an annotation is attached to is called a referent . Annotation data returned from the API includes both the substance of the annotation and the necessary information for displaying it in its original context. api.genius.com/ Try It Authorization: Bearer See details ing an access token in the authentication section below. Authenticate with the Docs App to Try GET /annotations/:id Data for a specific annotation. id ID of the annotation text_format Format for text bodies related to the document. One or more of dom , plain , and html , separated by commas (defaults to dom ). See details of each option here POST /annotations Requires scope: create_annotation Creates a new annotation on a public web page. The returned value will be the new annotation object, in the same form as would be returned by GET /annotation/:id with the new annotation’s ID. Example Payload: { "annotation" : { "body" : { "markdown" : "hello **world!**" } }, "referent" : { "raw_annotatable_url" : "http://seejohncode.com/2014/01/27/vim-commands-piping/" , "fragment" : "execute commands" , "context_for_display" : { "before_html" : "You may know that you can " , "after_html" : " from inside of vim, with a vim command:" } }, "web_page" : { "canonical_url" : null , "og_url" : null , "title" : "Secret of Mana" } } annotation body markdown Required The text for the note, in markdown referent raw_annotatable_url Required The original URL of the page fragment Required The highlighted fragment context_for_display before_html The HTML before the highlighted fragment (prefer up to 200 characters) after_html The HTML after the highlighted fragment (prefer up to 200 characters) web_page At least one required canonical_url The href property of the link rel="canonical" tag on the page. Including it will help make sure newly created annotation appear on the correct page og_url The content property of the meta property="og:url" tag on the page. Including it will help make sure newly created annotation appear on the correct page title The title of the page PUT /annotations/:id Requires scope: manage_annotation Updates an annotation created by the authenticated user. Accepts the same parameters as POST /annotation above. DELETE /annotations/:id Requires scope: manage_annotation Deletes an annotation created by the authenticated user. PUT /annotations/:id/upvote Requires scope: vote Votes positively for the annotation on behalf of the authenticated user. PUT /annotations/:id/downvote Requires scope: vote Votes negatively for the annotation on behalf of the authenticated user. PUT /annotations/:id/unvote Requires scope: vote Removes the authenticated user’s vote (up or down) for the annotation. Referents Referents are the sections of a piece of content to which annotations are attached. Each referent is associated with a web page or a song and may have one or more annotations. Referents can be searched by the document they are attached to or by the user that created them. When a new annotation is created either a referent is created with it or that annotation is attached to an existing referent. api.genius.com/ Try It Authorization: Bearer See details ing an access token in the authentication section below. Authenticate with the Docs App to Try GET /referents Referents by content item or user responsible for an included annotation. You may pass only one of song_id and web_page_id , not both. created_by_id ID of a user to get referents for song_id ID of a song to get referents for web_page_id ID of a web page to get referents for text_format Format for text bodies related to the document. One or more of dom , plain , and html , separated by commas (defaults to dom ). See details of each option here per_page Number of results to return per request page Paginated offset, (e.g., per_page=5&page=3 returns songs 11–15) Songs A song is a document hosted on Genius. It’s usually music lyrics. Data for a song includes details about the document itself and information about all the referents that are attached to it, including the text to which they refer. api.genius.com/ Try It Authorization: Bearer See details ing an access token in the authentication section below. Authenticate with the Docs App to Try GET /songs/:id Data for a specific song. id ID of the song text_format Format for text bodies related to the document. One or more of dom , plain , and html , separated by commas (defaults to dom ). See details of each option here Artists An artist is how Genius represents the creator of one or more songs (or other documents hosted on Genius). It’s usually a musician or group of musicians. api.genius.com/ Try It Authorization: Bearer See details ing an access token in the authentication section below. Authenticate with the Docs App to Try GET /artists/:id Data for a specific artist. id ID of the artist text_format Format for text bodies related to the document. One or more of dom , plain , and html , separated by commas (defaults to dom ). See details of each option here api.genius.com/ Try It Authorization: Bearer See details ing an access token in the authentication section below. Authenticate with the Docs App to Try GET /artists/:id/songs Documents (songs) for the artist specified. By default, 20 items are returned for each request. id ID of the artist. sort title (default) or popularity per_page Number of results to return per request page Paginated offset, (e.g., per_page=5&page=3 returns songs 11–15) Web Pages A web page is a single, publicly accessible page to which annotations may be attached. Web pages map 1-to-1 with unique, canonical URLs. api.genius.com/ Try It Authorization: Bearer See details ing an access token in the authentication section below. Authenticate with the Docs App to Try GET /web_pages/lookup Information about a web page retrieved by the page’s full URL (including protocol). The returned data includes Genius’s ID for the page, which may be used to look up associated referents with the /referents...