{"id":29682763,"url":"https://github.com/et0and/natto","last_synced_at":"2026-01-20T16:26:39.883Z","repository":{"id":305640542,"uuid":"1014170522","full_name":"et0and/natto","owner":"et0and","description":"A multi-service API 🫘","archived":false,"fork":false,"pushed_at":"2025-10-03T04:00:41.000Z","size":1522,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-22T20:29:45.202Z","etag":null,"topics":["hono","sqlite"],"latest_commit_sha":null,"homepage":"https://natto.tom.so/artists","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/et0and.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-05T07:27:15.000Z","updated_at":"2025-07-27T04:37:20.000Z","dependencies_parsed_at":"2025-10-03T05:31:05.919Z","dependency_job_id":"dcfab332-176c-4fac-9522-165ac05684d7","html_url":"https://github.com/et0and/natto","commit_stats":null,"previous_names":["et0and/natto"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/et0and/natto","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/et0and%2Fnatto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/et0and%2Fnatto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/et0and%2Fnatto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/et0and%2Fnatto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/et0and","download_url":"https://codeload.github.com/et0and/natto/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/et0and%2Fnatto/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28607034,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T16:10:39.856Z","status":"ssl_error","status_checked_at":"2026-01-20T16:10:39.493Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hono","sqlite"],"created_at":"2025-07-23T03:01:02.202Z","updated_at":"2026-01-20T16:26:39.867Z","avatar_url":"https://github.com/et0and.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Natto hero](natto.png)\n\n# 🫘 Natto - a hobby API service\n\n**Natto** is a multi-purpose hobby API service that provides access to various personal interests and collections. It mainly focuses on Asian artists from the [Getty Research Institute's Union List of Artist Names® (ULAN) database](https://www.getty.edu/research/tools/vocabularies/ulan), but also includes multiple API endpoints covering different personal interests including a directory of art galleries in Aotearoa, my books, Tomica car collections et al.\n\nI'm using this project to learn more about [Hono](https://hono.dev/) and what it is capable of just as a bit of fun!\n\n## About the data\n\nNatto contains multiple datasets across different domains:\n\n### Artists from Asia\nThe artist data is derived from the ULAN database, which contains authoritative information about artists and their biographical details. The data includes:\n\n- Artist names and full names\n- Nationality codes and geographic origins\n- Artist types and classifications\n- Biographical descriptions\n- Hierarchical relationships between artists\n- Information on submitter\n\nCurrently it contains over a million records stored in a single SQLite database, with more being added over time.\n\n### Galleries\nGallery data includes information about art galleries and exhibition spaces:\n\n- Gallery names and descriptions\n- Physical addresses and contact information\n- Geographic coordinates (latitude/longitude)\n- Associated artists\n- Opening year and operational status\n- Website and email contact details\n\n### Planned Collections\nAdditional datasets are planned for:\n\n- **Books**: Personal book collection with titles, authors, genres, and descriptions\n- **Cars**: Tomica die-cast car collection with models, brands, years, and colours\n\n### Attribution and thanks\n\nThis project contains information from the J. Paul Getty Trust, Getty Research Institute, the Union List of Artist Names, which is made available under the ODC Attribution License. The Getty Vocabulary data is compiled from various contributors using published sources; the contributor and sources are available as part of each record.\n\nFor more information about the Getty Vocabularies and their licensing, visit the [Getty Research Institute Download Center](https://www.getty.edu/research/tools/vocabularies/obtain.html).\n\nBesides the data, the source code of this project is [GPLv3 licensed](/LICENSE).\n\n## API endpoints\n\n### Health check\n\n- **GET** `/health` - Returns service health status\n\n### Artists\n\n#### Get all artists (paginated response)\n\n- **GET** `/artists` - Retrieve a paginated list of artists with optional filtering\n\n**Query parameters:**\n\n- `page` (integer, default: 1) - Page number for pagination\n- `limit` (integer, default: 20) - Number of results per page\n- `name` (string) - Search artists by name (partial match)\n- `type` (string) - Filter by artist type\n- `nationalityCode` (string) - Filter by nationality code\n\n**Example requests:**\n\n```bash\n# Get first page of artists\nGET /artists\n\n# Search for artists with \"zhang\" in their name\nGET /artists?name=zhang\n\n# Get Chinese artists (note: we will be cleaning the data in the future to not include the numeric code as part of this in the future)\nGET /artists?nationalityCode=936010/Chinese\n\n# Get photographers with pagination\nGET /artists?type=31407/photographer\u0026page=2\u0026limit=10\n\n# Combined filters\nGET /artists?name=li\u0026nationalityCode=936010/Chinese\u0026type=31407/photographer\u0026page=1\u0026limit=5\n```\n\n**Response:**\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": \"artist_id\",\n      \"parentId\": \"parent_artist_id\",\n      \"name\": \"Artist Name\",\n      \"termId\": \"term_identifier\",\n      \"contributorId\": \"contributor_id\",\n      \"fullName\": \"Full Artist Name\",\n      \"type\": \"artist_type\",\n      \"nationalityCode\": \"nationality_code\",\n      \"description\": \"Artist description\"\n    }\n  ],\n  \"pagination\": {\n    \"page\": 1,\n    \"limit\": 20,\n    \"total\": 1500,\n    \"totalPages\": 75,\n    \"hasNext\": true,\n    \"hasPrev\": false\n  },\n  \"filters\": {\n    \"name\": \"search_term\",\n    \"type\": \"filter_value\",\n    \"nationalityCode\": \"nationality_filter\"\n  }\n}\n```\n\n#### Get single artist\n\n- **GET** `/artists/:id` - Retrieve a specific artist by ID\n\n**Example request:**\n\n```bash\nGET /artists/500115493\n```\n\n**Response:**\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": \"500115493\",\n    \"parentId\": null,\n    \"name\": \"Artist Name\",\n    \"termId\": \"term_id\",\n    \"contributorId\": \"contributor_id\",\n    \"fullName\": \"Full Artist Name\",\n    \"type\": \"painter\",\n    \"nationalityCode\": \"JP\",\n    \"description\": \"Artist biographical information\"\n  }\n}\n```\n\n### Galleries\n\n#### Get all galleries (paginated response)\n\n- **GET** `/galleries` - Retrieve a paginated list of galleries with optional filtering\n\n**Query parameters:**\n\n- `page` (integer, default: 1) - Page number for pagination\n- `limit` (integer, default: 20) - Number of results per page\n- `name` (string) - Search galleries by name (partial match)\n- `address` (string) - Filter by exact address match\n\n**Example requests:**\n\n```bash\n# Get first page of galleries\nGET /galleries\n\n# Search for galleries with \"modern\" in their name\nGET /galleries?name=modern\n\n# Get galleries at a specific address\nGET /galleries?address=123 Art Street\n\n# Combined filters with pagination\nGET /galleries?name=gallery\u0026page=2\u0026limit=5\n```\n\n**Response:**\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": \"gallery_id\",\n      \"name\": \"Gallery Name\",\n      \"description\": \"Gallery description\",\n      \"address\": \"123 Art Street, City\",\n      \"website\": \"https://gallery.com\",\n      \"email\": \"info@gallery.com\",\n      \"artists\": \"associated_artists\",\n      \"latitude\": \"40.7128\",\n      \"longitude\": \"-74.0060\",\n      \"status\": 1,\n      \"opened\": 1995,\n      \"createdAt\": \"2024-01-01T00:00:00.000Z\",\n      \"updatedAt\": \"2024-01-01T00:00:00.000Z\"\n    }\n  ],\n  \"pagination\": {\n    \"page\": 1,\n    \"limit\": 20,\n    \"total\": 150,\n    \"totalPages\": 8,\n    \"hasNext\": true,\n    \"hasPrev\": false\n  },\n  \"filters\": {\n    \"name\": \"search_term\",\n    \"type\": \"address_filter\"\n  }\n}\n```\n\n#### Get single gallery\n\n- **GET** `/galleries/:id` - Retrieve a specific gallery by ID\n\n**Example request:**\n\n```bash\nGET /galleries/gallery_123\n```\n\n**Response:**\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": \"gallery_123\",\n    \"name\": \"Modern Art Gallery\",\n    \"description\": \"Contemporary art space featuring emerging artists\",\n    \"address\": \"456 Culture Ave, Art District\",\n    \"website\": \"https://modernartgallery.com\",\n    \"email\": \"contact@modernartgallery.com\",\n    \"artists\": \"artist1,artist2,artist3\",\n    \"latitude\": \"40.7589\",\n    \"longitude\": \"-73.9851\",\n    \"status\": 1,\n    \"opened\": 2010,\n    \"createdAt\": \"2024-01-01T00:00:00.000Z\",\n    \"updatedAt\": \"2024-01-01T00:00:00.000Z\"\n  }\n}\n```\n\n### Planned API Routes\n\nThe following API endpoints are planned for future implementation:\n\n#### Books\n- **GET** `/books` - Retrieve paginated book collection\n- **GET** `/books/:id` - Get specific book details\n- Query parameters: `title`, `author`, `genre`, `year`\n\n#### Cars (Personal Tomica collection)\n- **GET** `/cars` - Retrieve paginated car collection\n- **GET** `/cars/:id` - Get specific car details\n- Query parameters: `model`, `brand`, `year`, `colour`\n\n## Stack\n\nNatto uses the following awesome technologies:\n\n- **Framework**: [Hono](https://hono.dev/) - Fast web framework by [Yusuke Wada](https://github.com/yusukebe)\n- **Database**: SQLite/LibSQL with [Drizzle ORM](https://orm.drizzle.team/)\n- **Tests**: [Vitest](https://vitest.dev/)\n- **Linter**: [Oxlint](https://oxc.rs/docs/guide/usage/linter.html) - Incredibly fast linter\n- **Runtime**: Cloudflare Workers (although Hono and everything else here will happily run anywhere!)\n\n## Development\n\n### Prerequisites\n\n- Node.js 18+\n- npm or bun\n\n### Setup\n\n```bash\n# Install dependencies\nbun install\n\n# Start development server\nbun dev\n\n# Run tests\nbun test\n\n# Lint code\nbun run lint\n```\n\n### Deployment\n\n```bash\n# Build and deploy to Cloudflare Workers\nbun run deploy\n\n# Generate Cloudflare types\nbun run cf-typegen\n```\n\n### Configuration\n\nThe application uses Cloudflare Workers bindings for database configuration:\n\n```ts\n// src/index.ts\nconst app = new Hono\u003c{ Bindings: CloudflareBindings }\u003e();\n```\n\nRequired environment variables:\n\n- `DATABASE_URL` - LibSQL database connection URL\n- `DATABASE_AUTH_TOKEN` - Database authentication token\n- `CLOUDFLARE_API_TOKEN` - Cloudflare API token for deployment (if not using `wrangler login`)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fet0and%2Fnatto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fet0and%2Fnatto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fet0and%2Fnatto/lists"}