Keyword research

curl --fail-with-body -sS -G https://api.alura.io/v1/research/keywords \
  -H "Authorization: Bearer $ALURA_API_KEY" \
  --data-urlencode "q=personalized mug" \
  --data-urlencode "q=name mug" \
  --data-urlencode "language=en"

interface Keyword {
  id: string;
  keyword: string;
  volume: { etsy_monthly: number | null };
  competition: { level: string | null; competing_listings: number | null };
  trend: { change_3m: number | null };
}
interface Lookup {
  data: Keyword[];
  pending: { keyword: string }[];
  unfetched: { keyword: string; code: string; retry_after: number }[];
  not_found: { keyword: string }[];
}

const url = new URL('https://api.alura.io/v1/research/keywords');
for (const q of ['personalized mug', 'name mug']) url.searchParams.append('q', q);
url.searchParams.set('language', 'en');

const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.ALURA_API_KEY}` } });
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const result = (await res.json()) as Lookup;

for (const k of result.data) {
  console.log(`${k.keyword} (id ${k.id}): ${k.volume.etsy_monthly ?? 'unknown'} Etsy searches a month, competition ${k.competition.level ?? 'unknown'}`);
}
for (const k of result.unfetched) console.log(`${k.keyword}: not available yet (${k.code}), retry in ${k.retry_after}s`);

import json
import os
import urllib.parse
import urllib.request

# Repeat q once per keyword; keywords may contain commas.
query = urllib.parse.urlencode([("q", "personalized mug"), ("q", "name mug"), ("language", "en")])
request = urllib.request.Request(
    f"https://api.alura.io/v1/research/keywords?{query}",
    headers={"Authorization": f"Bearer {os.environ['ALURA_API_KEY']}"},
)
with urllib.request.urlopen(request) as response:
    result = json.load(response)

for k in result["data"]:
    volume = k["volume"]["etsy_monthly"]
    print(f"{k['keyword']} (id {k['id']}): {'unknown' if volume is None else volume} Etsy searches a month, competition {k['competition']['level'] or 'unknown'}")
for k in result["unfetched"]:
    print(f"{k['keyword']}: not available yet ({k['code']}), retry in {k['retry_after']}s")

curl --fail-with-body -sS https://api.alura.io/v1/research/keywords/88123/related \
  -H "Authorization: Bearer $ALURA_API_KEY"

curl --fail-with-body -sS -G https://api.alura.io/v1/research/keywords/88123/products \
  -H "Authorization: Bearer $ALURA_API_KEY" \
  --data-urlencode "limit=5"

interface Keyword {
  keyword: string;
  volume: { etsy_monthly: number | null };
}
interface Product {
  id: string;
  title: string | null;
}

const get = async <T>(path: string): Promise<T> => {
  const res = await fetch(`https://api.alura.io${path}`, { headers: { Authorization: `Bearer ${process.env.ALURA_API_KEY}` } });
  if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
  return (await res.json()) as T;
};

// 88123 is the id GET /v1/research/keywords returned for "personalized mug".
const related = await get<{ data: Keyword[] }>('/v1/research/keywords/88123/related');
for (const k of related.data) console.log(`related: ${k.keyword} (${k.volume.etsy_monthly ?? 'unknown'} searches a month)`);

const top = await get<{ data: Product[] }>('/v1/research/keywords/88123/products?limit=5');
for (const p of top.data) console.log(`ranks: ${p.id} ${p.title}`);

import json
import os
import urllib.request


def get(path):
    request = urllib.request.Request(
        f"https://api.alura.io{path}",
        headers={"Authorization": f"Bearer {os.environ['ALURA_API_KEY']}"},
    )
    with urllib.request.urlopen(request) as response:
        return json.load(response)


# 88123 is the id GET /v1/research/keywords returned for "personalized mug".
for k in get("/v1/research/keywords/88123/related")["data"]:
    volume = k["volume"]["etsy_monthly"]
    print(f"related: {k['keyword']} ({'unknown' if volume is None else volume} searches a month)")

for p in get("/v1/research/keywords/88123/products?limit=5")["data"]:
    print(f"ranks: {p['id']} {p['title']}")

curl --fail-with-body -sS https://api.alura.io/v1/research/products/4524717183/tags \
  -H "Authorization: Bearer $ALURA_API_KEY"

interface Tag {
  tag: string;
  keyword: { id: string; volume: { etsy_monthly: number | null }; competition: { level: string | null } } | null;
}

const res = await fetch('https://api.alura.io/v1/research/products/4524717183/tags', {
  headers: { Authorization: `Bearer ${process.env.ALURA_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const page = (await res.json()) as { data: Tag[] };

for (const t of page.data) {
  console.log(t.keyword ? `${t.tag}: ${t.keyword.volume.etsy_monthly ?? 'unknown'} searches a month, competition ${t.keyword.competition.level ?? 'unknown'}` : `${t.tag}: no keyword data`);
}

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://api.alura.io/v1/research/products/4524717183/tags",
    headers={"Authorization": f"Bearer {os.environ['ALURA_API_KEY']}"},
)
with urllib.request.urlopen(request) as response:
    page = json.load(response)

for t in page["data"]:
    k = t["keyword"]
    if k is None:
        print(f"{t['tag']}: no keyword data")
    else:
        volume = k["volume"]["etsy_monthly"]
        print(f"{t['tag']}: {'unknown' if volume is None else volume} searches a month, competition {k['competition']['level'] or 'unknown'}")