Openverseは、クリエイティブ・コモンズのライセンスの下で公開されている画像や音楽などのデジタルコンテンツを検索できるプラットフォームです。この記事では、Openverse APIをJavaで利用する方法について詳しく解説します。
Openverseについて
Openverseは、クリエイティブ・コモンズのライセンスを持つデジタルコンテンツを検索するためのプラットフォームです。ユーザーは、このプラットフォームを使用して、ライセンスの条件下で自由に使用できる画像や音楽などのコンテンツを見つけることができます。
Openverse APIの認証
Openverse APIを利用するには、まずAPIキーを取得する必要があります。以下の手順でAPIキーを取得できます：
- Openverse APIの公式ドキュメントにアクセスします。
-
auth_tokens/register/エンドポイントを使用して、アプリケーションの名前、説明、およびメールアドレスを登録します。 - 登録が完了すると、
client_idとclient_secretが返されます。 - これらの情報を使用して、
auth_tokens/token/エンドポイントを呼び出し、アクセストークンを取得します。
以下は、OpenverseのAPIキーを取得するためのJavaのコード例です：
OpenverseAuth.java
package openverse4j;
import org.json.JSONObject;
import okhttp3.FormBody;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
/**
* OpenverseAuth provides methods to authenticate with the Openverse API.
* It allows users to register their application and retrieve an access token.
*/
public class OpenverseAuth {
private static final String REGISTER_URL = "https://api.openverse.engineering/v1/auth_tokens/register/";
private static final String TOKEN_URL = "https://api.openverse.engineering/v1/auth_tokens/token/";
private static final OkHttpClient client = new OkHttpClient();
/**
* The main method to demonstrate the registration and token retrieval process.
*
* @param args Command-line arguments (not used).
*/
public static void main(final String[] args) {
// アプリ情報やメールを設定
final var appName = "YOUR_APP_NAME";
final var appDescription = "YOUR_APP_DESCRIPTION";
final var email = "YOUR_EMAIL";
// 1. APIキーの取得
final var credentials = OpenverseAuth.register(appName, appDescription, email);
final var clientId = credentials[0];
final var clientSecret = credentials[1];
System.out.println("ClientId: " + clientId);
System.out.println("ClientSecret: " + clientSecret);
// 2. アクセストークンの取得
final var accessToken = OpenverseAuth.getAccessToken(clientId, clientSecret);
System.out.println("Access Token: " + accessToken);
}
/**
* Registers an application with the Openverse API.
*
* @param appName The name of the application.
* @param appDescription A brief description of the application.
* @param email The email address associated with the application.
* @return An array containing the client ID and client secret.
*/
public static String[] register(final String appName, final String appDescription, final String email) {
try {
final var jsonParam = new JSONObject();
jsonParam.put("name", appName);
jsonParam.put("description", appDescription);
jsonParam.put("email", email);
final var body = RequestBody.create(jsonParam.toString(), MediaType.parse("application/json; charset=utf-8"));
final var request = new Request.Builder()
.url(OpenverseAuth.REGISTER_URL)
.post(body)
.build();
final var response = OpenverseAuth.client.newCall(request).execute();
final var responseBody = response.body().string();
final var jsonResponse = new JSONObject(responseBody);
return new String[] { jsonResponse.getString("client_id"), jsonResponse.getString("client_secret") };
} catch (final Exception e) {
e.printStackTrace();
}
return null;
}
/**
* Retrieves an access token using the provided client ID and client secret.
*
* @param clientId The client ID obtained during registration.
* @param clientSecret The client secret obtained during registration.
* @return The access token.
*/
public static String getAccessToken(final String clientId, final String clientSecret) {
try {
final var formBody = new FormBody.Builder()
.add("grant_type", "client_credentials")
.add("client_id", clientId)
.add("client_secret", clientSecret)
.build();
final var request = new Request.Builder()
.url(OpenverseAuth.TOKEN_URL)
.post(formBody)
.build();
final var response = OpenverseAuth.client.newCall(request).execute();
final var responseBody = response.body().string();
final var jsonResponse = new JSONObject(responseBody);
return jsonResponse.getString("access_token");
} catch (final Exception e) {
e.printStackTrace();
}
return null;
}
}
JavaでのOpenverse APIの利用
JavaでOpenverse APIを利用するには、OkHttpというライブラリを使用します。以下は、Openverseの画像検索エンドポイントを利用するためのJavaのコード例です：
OpenverseImageAPI.java
package openverse4j;
import org.json.JSONObject;
import okhttp3.HttpUrl;
import okhttp3.OkHttpClient;
import okhttp3.Request;
/**
* OpenverseImageAPI provides methods to interact with the Openverse Image API.
* It allows users to search for images using a specific query.
*/
public class OpenverseImageAPI {
private static final String BASE_URL = "https://api.openverse.engineering/v1/images/";
private static final OkHttpClient client = new OkHttpClient();
/**
* The main method to demonstrate the image search process.
*
* @param args Command-line arguments (not used).
*/
public static void main(final String[] args) {
final var accessToken = "YOUR_ACCESS_TOKEN"; // 事前に取得したアクセストークンを設定
final var query = "test"; // 検索クエリ
// 画像検索
final var searchResult = OpenverseImageAPI.searchImages(accessToken, query);
System.out.println(searchResult.toString());
}
/**
* Searches for images on Openverse using the provided access token and query.
*
* @param accessToken The access token obtained from Openverse API.
* @param query The search query to find images.
* @return A JSONObject containing the search results.
*/
private static JSONObject searchImages(final String accessToken, final String query) {
try {
final var urlBuilder = HttpUrl.parse(OpenverseImageAPI.BASE_URL).newBuilder();
urlBuilder.addQueryParameter("q", query);
final var request = new Request.Builder()
.url(urlBuilder.build())
.addHeader("Authorization", "Bearer " + accessToken)
.build();
final var response = OpenverseImageAPI.client.newCall(request).execute();
final var responseBody = response.body().string();
return new JSONObject(responseBody);
} catch (final Exception e) {
e.printStackTrace();
}
return null;
}
}
このコードは、指定されたクエリを使用してOpenverseの画像検索エンドポイントを呼び出します。結果はJSON形式で返されます。
Mavenでのライブラリの追加
JavaプロジェクトでOkHttpを使用するには、Mavenを使用してライブラリを追加する必要があります。以下の依存関係をpom.xmlファイルに追加します：
<!-- JSON in Java (org.json) -->
<dependency>
<groupId>org.json</groupId>
<artifactId>json</artifactId>
<version>20230618</version>
</dependency>
<!-- OkHttp -->
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp</artifactId>
<version>4.11.0</version>
</dependency>
この依存関係をpom.xmlに追加した後、Mavenプロジェクトを更新することで、ライブラリがプロジェクトにダウンロードされ、利用可能になります。
まとめ
Openverse APIは、クリエイティブ・コモンズのライセンスの下で公開されているデジタルコンテンツを検索するための強力なツールです。Javaを使用してこのAPIを利用することで、アプリケーションやウェブサイトにライセンスフリーのコンテンツを組み込むことができます。