SearchLy API v1
Introduction
COMMUNITYNO AUTH0 INSTALLS
OpenAPI Specificationv3.0
{
"openapi": "3.0.1",
"servers": [
{
"url": "https://searchly.asuarez.dev/api/v1"
}
],
"info": {
"contact": {
"email": "hi@asuarez.dev"
},
"description": "# Introduction\nThe SearchLy API provides similarity searching based on song lyrics.\n\n# Operations\nThe API allows for the `/similarity/by_song` operation, which allows clients to search the similarity for an existing song in the database. Also, the API has an additional `/similarity/by_content` endpoint which allows clients to search similarity given a free String input through a JSON request body. Additional `/song/search` operation is available for searching songs given a query String.\n\n# Endpoint\nThe API endpoint for the SearchLy API v1 is as follows:\n```\nhttps://searchly.asuarez.dev/api/v1\n```\n\n# Motivation\nThis project was built in order to create an API for searching similarities based on song lyrics. There are a lot of songs in the industry and most of them are talking about the same topic. What I wanted to prove with SearchLy was to estimate how similar are two songs between them based on the meaning of their lyrics.\n\nSearchLy is using a database of 100k songs from AZLyrics, using [this scraper](https://github.com/AlbertSuarez/azlyrics-scraper), which is being updated periodically. Then, using word2vec and NMSLIB, it was possible to create an index where you can search similarities using the k-nearest neighbors (KNN) algorithm.\n\n> **Note**: I am currently using a micro-instance from DigitalOcean where the API is deployed, so you should expect a bad performance. However, if this API becomes popular I will deploy it in a bigger instance.\n",
"title": "SearchLy API v1",
"version": "1.0",
"x-apisguru-categories": [
"media"
],
"x-origin": [
{
"format": "openapi",
"url": "https://raw.githubusercontent.com/AlbertSuarez/searchly/master/src/searchly/static/openapi/openapi_v1.yaml",
"version": "3.0"
}
],
"x-providerName": "asuarez.dev",
"x-serviceName": "searchly",
"x-logo": {
"url": "https://api.apis.guru/v2/cache/logo/https_apis.guru_assets_images_no-logo.svg"
}
},
"externalDocs": {
"description": "SearchLy demo",
"url": "https://searchly.asuarez.dev/"
},
"tags": [
{
"name": "similarity",
"x-displayName": "Similarity search"
},
{
"name": "song",
"x-displayName": "Song search"
}
],
"paths": {
"/similarity/by_content": {
"post": {
"description": "Endpoint for an end-user client to search similarity by content.\n\nIf you want to run the /similarity/by_content operation, you can do so via an HTTP POST command to the following URL:\n\n```\nhttps://searchly.asuarez.dev/api/v1/similarity/by_content\n```\n",
"operationId": "src.searchly.api.v1.controllers.similarity.by_content",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"content": {
"description": "Content for searching similarity.",
"type": "string"
}
},
"type": "object"
}
}
},
"description": "Body wrapper for the request.",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIResponseSimilarity"
}
}
},
"description": "Standard SearchLy API v1 JSON response. You should check the `error` attribute to determine if there was an error."
},
"default": {
"content": {
"application/text": {
"schema": {
"description": "Error description.",
"type": "string"
}
}
},
"description": "Unexpected error."
}
},
"summary": "API endpoint to search similarity using content",
"tags": [
"similarity"
],
"x-code-samples": [
{
"lang": "python",
"source": "# Make sure you have installed the required packages:\n# pip install requests\n\nimport requests\n\nurl = 'https://searchly.asuarez.dev/api/v1/similarity/by_content'\nrequest_body = {\"content\": \"CONTENT\"}\n\n# Make the classify request\nresponse = requests.post(url, json=request_body)\n\n# The response is formatted in JSON\njson_response = response.json()\n"
},
{
"lang": "Java",
"source": "try {\n URL myurl = new URL(\"https://searchly.asuarez.dev/api/v1/similarity/by_content\");\n con = (HttpURLConnection) myurl.openConnection();\n con.setRequestMethod(\"POST\");\n StringBuilder content;\n\n String jsonInputString = \"{\" +\n \"\\\"content\\\": \\\"CONTENT\\\"\" +\n \"}\";\n try (OutputStream os = con.getOutputStream()) {\n byte[] input = jsonInputString.getBytes(\"utf-8\");\n os.write(input, 0, input.length);\n }\n\n try (BufferedReader br = new BufferedReader(\n new InputStreamReader(con.getInputStream(), \"utf-8\"))) {\n StringBuilder response = new StringBuilder();\n String responseLine = null;\n while ((responseLine = br.readLine()) != null) {\n response.append(responseLine.trim());\n }\n System.out.println(response.toString());\n }\n\n} finally {\n con.disconnect();\n}\n"
},
{
"lang": "C#",
"source": "var httpWebRequest = (HttpWebRequest)WebRequest.Create(\"https://searchly.asuarez.dev/api/v1/similarity/by_content\");\nhttpWebRequest.ContentType = \"application/json\";\nhttpWebRequest.Method = \"POST\";\n\nusing (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))\n{\n string json = \"{\" +\n \"\\\"content\\\": \\\"CONTENT\\\"\" +\n \"}\";\n streamWriter.Write(json);\n}\n\nvar httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();\nusing (var streamReader = new StreamReader(httpResponse.GetResponseStream()))\n{\n var result = streamReader.ReadToEnd();\n}\n"
},
{
"lang": "php",
"source": "<?php\n // The data to send to the API\n $postData = array(\n 'content' => 'CONTENT'\n );\n\n // Setup cURL\n $ch = curl_init('https://searchly.asuarez.dev/api/v1/similarity/by_content');\n curl_setopt_array($ch, array(\n CURLOPT_POST => TRUE,\n CURLOPT_RETURNTRANSFER => TRUE,\n CURLOPT_HTTPHEADER => array(\n 'Content-Type: application/json'\n ),\n CURLOPT_POSTFIELDS => json_encode($postData)\n ));\n\n // Send the request\n $response = curl_exec($ch);\n?>\n"
},
{
"lang": "shell",
"source": "curl \"https://searchly.asuarez.dev/api/v1/similarity/by_content\"\\\n-d content=\"CONTENT\"\n"
}
]
}
},
"/similarity/by_song": {
"get": {
"description": "Endpoint for an end-user client to search similarity by song identifier.\n\nIf you want to run the /similarity/by_song operation, you can do so via an HTTP GET command to the following URL:\n\n```\nhttps://searchly.asuarez.dev/api/v1/similarity/by_song\n```\n",
"operationId": "src.searchly.api.v1.controllers.similarity.by_song",
"parameters": [
{
"description": "Song identifier.",
"example": 234,
"in": "query",
"name": "song_id",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIResponseSimilarity"
}
}
},
"description": "Standard SearchLy API v1 JSON response. You should check the `error` attribute to determine if there was an error."
},
"default": {
"content": {
"application/text": {
"schema": {
"description": "Error description.",
"type": "string"
}
}
},
"description": "Unexpected error."
}
},
"summary": "API endpoint to search similarity using a song identifier",
"tags": [
"similarity"
],
"x-code-samples": [
{
"lang": "python",
"source": "# Make sure you have installed the required packages:\n# pip install requests\n\nimport requests\n\nurl = 'https://searchly.asuarez.dev/api/v1/similarity/by_song'\npayload = {'song_id': SONG_IDENTIFIER}\n\n# Make the classify request\nresponse = requests.get(url, params=payload)\n\n# The response is formatted in JSON\njson_response = response.json()\n"
},
{
"lang": "Java",
"source": "try {\n URL myurl = new URL(\"https://searchly.asuarez.dev/api/v1/similarity/by_song\" +\n \"?song_id=\" + \"SONG_IDENTIFIER\");\n con = (HttpURLConnection) myurl.openConnection();\n con.setRequestMethod(\"GET\");\n StringBuilder content;\n\n try (BufferedReader br = new BufferedReader(\n new InputStreamReader(con.getInputStream(), \"utf-8\"))) {\n StringBuilder response = new StringBuilder();\n String responseLine = null;\n while ((responseLine = br.readLine()) != null) {\n response.append(responseLine.trim());\n }\n System.out.println(response.toString());\n }\n\n} finally {\n con.disconnect();\n}\n"
},
{
"lang": "C#",
"source": "var httpWebRequest = (HttpWebRequest)WebRequest.Create(\"https://searchly.asuarez.dev/api/v1/similarity/by_song\" +\n \"?song_id=\" + \"SONG_IDENTIFIER\");\nhttpWebRequest.Method = \"GET\";\n\nvar httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();\nusing (var streamReader = new StreamReader(httpResponse.GetResponseStream()))\n{\n var result = streamReader.ReadToEnd();\n}\n"
},
{
"lang": "php",
"source": "<?php\n // Setup cURL\n $ch = curl_init('https://searchly.asuarez.dev/api/v1/similarity/by_song'.'?song_id='.'SONG_IDENTIFIER');\n\n // Send the request\n $response = curl_exec($ch);\n?>\n"
},
{
"lang": "shell",
"source": "curl \"https://searchly.asuarez.dev/api/v1/similarity/by_song?song_id=SONG_IDENTIFIER\"\n"
}
]
}
},
"/song/search": {
"get": {
"description": "Endpoint for an end-user client to search songs from the database given a String query.\n\nIf you want to run the /song/search operation, you can do so via an HTTP GET command to the following URL:\n\n```\nhttps://searchly.asuarez.dev/api/v1/song/search\n```\n",
"operationId": "src.searchly.api.v1.controllers.song.search",
"parameters": [
{
"description": "Query.",
"example": "Miley Cyrus",
"in": "query",
"name": "query",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIResponseSong"
}
}
},
"description": "Standard SearchLy API v1 JSON response. You should check the `error` attribute to determine if there was an error."
},
"default": {
"content": {
"application/text": {
"schema": {
"description": "Error description.",
"type": "string"
}
}
},
"description": "Unexpected error."
}
},
"summary": "API endpoint to search songs from the database given a query",
"tags": [
"song"
],
"x-code-samples": [
{
"lang": "python",
"source": "# Make sure you have installed the required packages:\n# pip install requests\n\nimport requests\n\nurl = 'https://searchly.asuarez.dev/api/v1/song/search'\npayload = {'query': 'QUERY'}\n\n# Make the classify request\nresponse = requests.get(url, params=payload)\n\n# The response is formatted in JSON\njson_response = response.json()\n"
},
{
"lang": "Java",
"source": "try {\n URL myurl = new URL(\"https://searchly.asuarez.dev/api/v1/song/search\" +\n \"?query=\" + \"QUERY\");\n con = (HttpURLConnection) myurl.openConnection();\n con.setRequestMethod(\"GET\");\n StringBuilder content;\n\n try (BufferedReader br = new BufferedReader(\n new InputStreamReader(con.getInputStream(), \"utf-8\"))) {\n StringBuilder response = new StringBuilder();\n String responseLine = null;\n while ((responseLine = br.readLine()) != null) {\n response.append(responseLine.trim());\n }\n System.out.println(response.toString());\n }\n\n} finally {\n con.disconnect();\n}\n"
},
{
"lang": "C#",
"source": "var httpWebRequest = (HttpWebRequest)WebRequest.Create(\"https://searchly.asuarez.dev/api/v1/song/search\" +\n \"?query=\" + \"QUERY\");\nhttpWebRequest.Method = \"GET\";\n\nvar httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();\nusing (var streamReader = new StreamReader(httpResponse.GetResponseStream()))\n{\n var result = streamReader.ReadToEnd();\n}\n"
},
{
"lang": "php",
"source": "<?php\n // Setup cURL\n $ch = curl_init('https://searchly.asuarez.dev/api/v1/song/search'.'?query='.'QUERY');\n\n // Send the request\n $response = curl_exec($ch);\n?>\n"
},
{
"lang": "shell",
"source": "curl \"https://searchly.asuarez.dev/api/v1/song/search?query=QUERY\"\n"
}
]
}
}
},
"components": {
"schemas": {
"APIResponseSimilarity": {
"properties": {
"error": {
"description": "Whether or not the request was successfully processed or not.",
"type": "boolean"
},
"message": {
"description": "Error message if the request was unsuccessful.",
"type": "string"
},
"response": {
"description": "Contains the response data if the request was successful.",
"properties": {
"similarity_list": {
"description": "Contains all the similarity items representing songs.",
"items": {
"description": "Song similarity item.",
"properties": {
"artist_name": {
"description": "Artist's song name.",
"type": "string"
},
"artist_url": {
"description": "Artist URL.",
"type": "string"
},
"id": {
"description": "Song internal identifier.",
"type": "integer"
},
"index_id": {
"description": "Index internal identifier.",
"type": "integer"
},
"lyrics": {
"description": "Song lyrics.",
"type": "string"
},
"percentage": {
"description": "Similarity percentage.",
"format": "float",
"type": "number"
},
"song_name": {
"description": "Song name.",
"type": "string"
},
"song_url": {
"description": "Song URL.",
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
},
"type": "object"
},
"APIResponseSong": {
"properties": {
"error": {
"description": "Whether or not the request was successfully processed or not.",
"type": "boolean"
},
"message": {
"description": "Error message if the request was unsuccessful.",
"type": "string"
},
"response": {
"description": "Contains the response data if the request was successful.",
"properties": {
"results": {
"description": "Contains all the songs.",
"items": {
"description": "Song item.",
"properties": {
"id": {
"description": "Song internal identifier.",
"type": "integer"
},
"name": {
"description": "Song and Artist name.",
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
},
"type": "object"
}
}
},
"x-logo": {
"altText": "SearchLy",
"url": "https://searchly.asuarez.dev/static/img/logo.png"
},
"x-tagGroups": [
{
"name": "Similarity",
"tags": [
"similarity"
]
},
{
"name": "Song",
"tags": [
"song"
]
}
]
}