quickstart.py

"""
Search + fetch a fragrance profile from the public Noteboxd API in Python.

    NOTEBOXD_API_KEY=nb_live_... python examples/python/quickstart.py oud

Uses only the standard library (urllib) so there are no dependencies to install.
Get a free key at https://developers.noteboxd.com
"""

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

API_KEY = os.environ.get("NOTEBOXD_API_KEY")
BASE = os.environ.get("NOTEBOXD_API_BASE_URL", "https://api.noteboxd.com")

if not API_KEY:
    sys.exit("Set NOTEBOXD_API_KEY. Get one free at https://developers.noteboxd.com")


def api(path: str) -> dict:
    req = urllib.request.Request(
        f"{BASE}{path}",
        headers={"Authorization": f"Bearer {API_KEY}", "Accept": "application/json"},
    )
    with urllib.request.urlopen(req) as resp:
        return json.load(resp)


def main() -> None:
    query = sys.argv[1] if len(sys.argv) > 1 else "oud"

    results = api(f"/v1/search?q={urllib.parse.quote(query)}&type=fragrance&limit=5")
    hits = results.get("data", [])
    if not hits:
        print(f"No fragrances found for {query!r}.")
        return

    print(f"Top matches for {query!r}:")
    for hit in hits:
        print(f"  • {hit.get('name')}  ({hit.get('slug')})")

    first_id = hits[0].get("id")
    if first_id:
        profile = api(f"/v1/fragrances/{urllib.parse.quote(first_id)}").get("data", {})
        print(f"\nProfile: {profile.get('name')}")
        print(f"  community score: {profile.get('communityScore')}")
        print(f"  family: {profile.get('familyPrimary')}")


if __name__ == "__main__":
    main()