コマンドリファレンス

よく使う呼び出しを、curl・PowerShell・Python・JavaScriptのコマンド例にまとめました。タブで切り替え、「コピー」で貼り付けられます。ベースURLは https://vrc.hachune.space/api/v1 です。

はじめに　User-Agent は必ず指定してください（例では my-app/1.0。ご自身のアプリ名に置き換えてください）。連続して呼ぶときは間隔を空けてください（利用ガイド）。

目次公開1週間以内のワールド季節・ジャンルで絞り込む名前・作者名で検索する（日本語）アバターの人気ランキング（1ページ目）アバター1件の詳細（価格推移・対応アイテム）IDを指定してまとめて取得する（ブックマーク）結果を絞り込む・保存する全ページを順に取得する（間隔を空ける）

パラメータ早見表

エンドポイント	パラメータ	値・意味
`/avatars`	`mode`	`popular`=人気 / `rising`=急上昇 / `new`=新着 / `bookmark`=ID指定
	`sort`	`rank / sale / price / price_desc / name / shop`
	`q`	アバター名・作者名の部分一致
	`page`	ページ番号（1ページ100件）
	`ids`	`mode=bookmark` のときの商品ID（カンマ区切り・最大300件）
`/avatar-detail`	`item_id`	BOOTHの商品ID（必須）
`/worlds`	`season`	`all / beginner / spring / summer / autumn / winter / chill / vsleep / jp_community / popular`
	`mode`	`rising`=お気に入りの伸び / `new`=公開1週間以内 / `bookmark`=ID指定
	`sort`	`favorites / name / author / newest / curator`
	`q`	ワールド名・作者名の部分一致
	`ids`	`mode=bookmark` のときのワールドID（最大300件）

公開1週間以内のワールド

GET GET /worlds　mode=new。配列が返ります。

curl -s -A "my-app/1.0" "https://vrc.hachune.space/api/v1/worlds?mode=new"

Invoke-RestMethod -Uri "https://vrc.hachune.space/api/v1/worlds?mode=new" -UserAgent "my-app/1.0"

import requests
r = requests.get("https://vrc.hachune.space/api/v1/worlds", params={"mode": "new"}, headers={"User-Agent": "my-app/1.0"}, timeout=20)
r.raise_for_status()
for w in r.json():
    print(w["name"], w["favorites"])

const res = await fetch("https://vrc.hachune.space/api/v1/worlds?mode=new", { headers: { "User-Agent": "my-app/1.0" } });
if (!res.ok) throw new Error(res.status);
const worlds = await res.json();
console.log(worlds.map(w => w.name));

季節・ジャンルで絞り込む

GET GET /worlds　season は all / beginner / spring / summer / autumn / winter / chill / vsleep / jp_community / popular。sort は favorites / name / author / newest / curator。

curl -s -A "my-app/1.0" "https://vrc.hachune.space/api/v1/worlds?season=autumn&sort=favorites"

Invoke-RestMethod -Uri "https://vrc.hachune.space/api/v1/worlds?season=autumn&sort=favorites" -UserAgent "my-app/1.0" | Select-Object -First 5 name, favorites

import requests
r = requests.get("https://vrc.hachune.space/api/v1/worlds", params={"season": "autumn", "sort": "favorites"}, headers={"User-Agent": "my-app/1.0"}, timeout=20)
print([w["name"] for w in r.json()[:5]])

const url = new URL("https://vrc.hachune.space/api/v1/worlds");
url.searchParams.set("season", "autumn");
url.searchParams.set("sort", "favorites");
const worlds = await (await fetch(url, { headers: { "User-Agent": "my-app/1.0" } })).json();
console.log(worlds.slice(0, 5).map(w => w.name));

名前・作者名で検索する（日本語）

GET GET /avatars　日本語などは URL エンコードが必要です。curl は -G --data-urlencode が簡単です。

curl -s -G -A "my-app/1.0" "https://vrc.hachune.space/api/v1/avatars" --data-urlencode "q=制服" --data-urlencode "sort=price"

$q = [uri]::EscapeDataString("制服")
Invoke-RestMethod -Uri "https://vrc.hachune.space/api/v1/avatars?q=$q&sort=price" -UserAgent "my-app/1.0"

import requests
r = requests.get("https://vrc.hachune.space/api/v1/avatars", params={"q": "制服", "sort": "price"}, headers={"User-Agent": "my-app/1.0"}, timeout=20)
print(r.json()["total"])

const url = new URL("https://vrc.hachune.space/api/v1/avatars");
url.searchParams.set("q", "制服");
url.searchParams.set("sort", "price");
const data = await (await fetch(url, { headers: { "User-Agent": "my-app/1.0" } })).json();
console.log(data.total);

アバターの人気ランキング（1ページ目）

GET GET /avatars　mode は popular / rising / new / bookmark。1ページ100件で、page で進めます。

curl -s -A "my-app/1.0" "https://vrc.hachune.space/api/v1/avatars?mode=popular&page=1"

$r = Invoke-RestMethod -Uri "https://vrc.hachune.space/api/v1/avatars?mode=popular&page=1" -UserAgent "my-app/1.0"
$r.items | Select-Object -First 10 rank_position, name, price

import requests
r = requests.get("https://vrc.hachune.space/api/v1/avatars", params={"mode": "popular", "page": 1}, headers={"User-Agent": "my-app/1.0"}, timeout=20).json()
for a in r["items"][:10]:
    print(a["rank_position"], a["name"], a["price"])

const data = await (await fetch("https://vrc.hachune.space/api/v1/avatars?mode=popular&page=1", { headers: { "User-Agent": "my-app/1.0" } })).json();
for (const a of data.items.slice(0, 10)) console.log(a.rank_position, a.name, a.price);

アバター1件の詳細（価格推移・対応アイテム）

GET GET /avatar-detail　item_id は BOOTH の商品IDです。

curl -s -A "my-app/1.0" "https://vrc.hachune.space/api/v1/avatar-detail?item_id=3853613"

Invoke-RestMethod -Uri "https://vrc.hachune.space/api/v1/avatar-detail?item_id=3853613" -UserAgent "my-app/1.0"

import requests
r = requests.get("https://vrc.hachune.space/api/v1/avatar-detail", params={"item_id": "3853613"}, headers={"User-Agent": "my-app/1.0"}, timeout=20)
print(r.status_code, r.json().get("item", {}).get("name"))

const res = await fetch("https://vrc.hachune.space/api/v1/avatar-detail?item_id=3853613", { headers: { "User-Agent": "my-app/1.0" } });
console.log(res.status, (await res.json()).item?.name);

IDを指定してまとめて取得する（ブックマーク）

GET GET /avatars・/worlds　mode=bookmark と ids（カンマ区切り・最大300件）。指定した順で返ります。

curl -s -A "my-app/1.0" "https://vrc.hachune.space/api/v1/avatars?mode=bookmark&ids=3853613,5380991"
curl -s -A "my-app/1.0" "https://vrc.hachune.space/api/v1/worlds?mode=bookmark&ids=wrld_aaeef9ec-c42e-4b95-870d-22bbc11a97aa"

Invoke-RestMethod -Uri "https://vrc.hachune.space/api/v1/avatars?mode=bookmark&ids=3853613,5380991" -UserAgent "my-app/1.0"

import requests
r = requests.get("https://vrc.hachune.space/api/v1/avatars", params={"mode": "bookmark", "ids": "3853613,5380991"}, headers={"User-Agent": "my-app/1.0"}, timeout=20)
print([a["name"] for a in r.json()["items"]])

const ids = ["3853613", "5380991"].join(",");
const data = await (await fetch("https://vrc.hachune.space/api/v1/avatars?mode=bookmark&ids=" + ids, { headers: { "User-Agent": "my-app/1.0" } })).json();
console.log(data.items.map(a => a.name));

結果を絞り込む・保存する

共通　jq が使えると、必要な項目だけ取り出せます。取得結果は手元に保存して使い回してください。

# 項目を絞る
curl -s -A "my-app/1.0" "https://vrc.hachune.space/api/v1/worlds?season=chill" | jq -r '.[:5][] | "\(.favorites)\t\(.name)"'
# ファイルに保存
curl -s -A "my-app/1.0" -o worlds-chill.json "https://vrc.hachune.space/api/v1/worlds?season=chill"

Invoke-RestMethod -Uri "https://vrc.hachune.space/api/v1/worlds?season=chill" -UserAgent "my-app/1.0" | ConvertTo-Json -Depth 5 | Set-Content -Encoding utf8 worlds-chill.json

import json, requests
r = requests.get("https://vrc.hachune.space/api/v1/worlds", params={"season": "chill"}, headers={"User-Agent": "my-app/1.0"}, timeout=20)
with open("worlds-chill.json", "w", encoding="utf-8") as f:
    json.dump(r.json(), f, ensure_ascii=False)

import { writeFile } from "node:fs/promises";
const worlds = await (await fetch("https://vrc.hachune.space/api/v1/worlds?season=chill", { headers: { "User-Agent": "my-app/1.0" } })).json();
await writeFile("worlds-chill.json", JSON.stringify(worlds));

全ページを順に取得する（間隔を空ける）

GET GET /avatars　has_more が false になるまで進めます。必ず間隔を空け、429 のときは Retry-After だけ待ってください。

for p in 1 2 3; do
  curl -s -A "my-app/1.0" "https://vrc.hachune.space/api/v1/avatars?mode=popular&page=$p" -o "avatars-$p.json"
  sleep 1
done

1..3 | ForEach-Object {
  Invoke-RestMethod -Uri "https://vrc.hachune.space/api/v1/avatars?mode=popular&page=$_" -UserAgent "my-app/1.0" | ConvertTo-Json -Depth 6 | Set-Content -Encoding utf8 "avatars-$_.json"
  Start-Sleep -Seconds 1
}

import time, requests
headers = {"User-Agent": "my-app/1.0"}
page, items = 1, []
while True:
    r = requests.get("https://vrc.hachune.space/api/v1/avatars", params={"mode": "popular", "page": page}, headers=headers, timeout=20)
    if r.status_code == 429:
        time.sleep(int(r.headers.get("Retry-After", "30")))
        continue
    r.raise_for_status()
    data = r.json()
    items += data["items"]
    if not data["has_more"] or page >= 5:
        break
    page += 1
    time.sleep(1)
print(len(items))

const headers = { "User-Agent": "my-app/1.0" };
const sleep = (ms) => new Promise(r => setTimeout(r, ms));
let page = 1, items = [];
while (true) {
  const res = await fetch("https://vrc.hachune.space/api/v1/avatars?mode=popular&page=" + page, { headers });
  if (res.status === 429) { await sleep(1000 * Number(res.headers.get("Retry-After") ?? 30)); continue; }
  if (!res.ok) throw new Error(res.status);
  const data = await res.json();
  items.push(...data.items);
  if (!data.has_more || page >= 5) break;
  page++; await sleep(1000);
}
console.log(items.length);