# TimGiup.com

> Nền tảng cộng đồng Việt Nam giúp tìm kiếm đồ thất lạc, thú cưng, người thân, giấy tờ và kết nối người nhặt được với chủ sở hữu. Website cung cấp API công khai, MCP server, RSS feed và sitemap để AI/LLM/crawler truy cập dữ liệu bài đăng một cách có cấu trúc. Vietnamese lost-and-found community platform with public API, MCP server, and RSS feeds.

## About

- Ngôn ngữ chính: Tiếng Việt (Search hỗ trợ có/không dấu) — Primary language: Vietnamese (search supports with/without diacritics)
- Phạm vi địa lý: 34 tỉnh/thành Việt Nam (sau sáp nhập hành chính 2025) — Coverage: 34 Vietnamese provinces (post-2025 administrative merger)
- 6 danh mục chính: đồ thất lạc, thú cưng thất lạc, người thân thất lạc, đồ nhặt được, cộng đồng giúp đỡ, khác
- Rate limit API: 30 requests/phút/IP
- Trả về tối đa 20 kết quả mỗi lần search

## API (JSON)

- [OpenAPI 3.1 Specification](https://timgiup.com/openapi.json): Full machine-readable API spec — paste vào ChatGPT/Claude/codegen tool để sinh client tự động
- [Search Posts](https://timgiup.com/api/search?q=iphone): `GET /api/search?q={keyword}&category={slug}&province={code}` — tìm kiếm bài đăng theo từ khóa, danh mục, tỉnh/thành. Trả về tối đa 20 bài JSON kèm title, status, mô tả, danh mục, địa chỉ, ngày, ảnh, source URL
- [List Provinces](https://timgiup.com/api/provinces): 34 tỉnh/thành kèm `aliases` (tên tỉnh cũ đã sáp nhập) — dùng để map tên cũ → mã đơn vị mới
- [List Categories](https://timgiup.com/api/categories): Danh mục cha với `slug` dùng làm filter cho `/api/search`

## MCP Server (Model Context Protocol)

- [timgiup-mcp-server (GitHub)](https://github.com/timgiup/timgiup-mcp-server): MCP server cho Claude Desktop, Claude Code, Cline, Cursor — gọi trực tiếp search/categories/provinces từ AI agent. Cài đặt một dòng: `uvx --from git+https://github.com/timgiup/timgiup-mcp-server timgiup-mcp`. Cung cấp 3 tools: `search_lost_items`, `list_categories`, `list_provinces`

## RSS Feeds

- [RSS Index Page](https://timgiup.com/rss): Trang giới thiệu các feed RSS có sẵn
- [All Posts Feed](https://timgiup.com/rss/tat-ca.rss): RSS 2.0 — 20 bài đăng mới nhất từ tất cả danh mục
- [Lost Items Feed](https://timgiup.com/rss/do-that-lac.rss): Đồ thất lạc (điện thoại, ví, giấy tờ, ...)
- [Lost Pets Feed](https://timgiup.com/rss/thu-cung-that-lac.rss): Thú cưng thất lạc (chó, mèo, ...)
- [Missing Persons Feed](https://timgiup.com/rss/nguoi-than-that-lac.rss): Người thân thất lạc
- [Found Items Feed](https://timgiup.com/rss/do-nhat-duoc.rss): Đồ nhặt được, chờ trả lại chủ
- [Community Help Feed](https://timgiup.com/rss/cong-dong-giup-do.rss): Cộng đồng giúp đỡ

## Sitemaps (SEO)

- [Sitemap Index](https://timgiup.com/sitemap.xml): Root sitemap index
- [Static Pages Sitemap](https://timgiup.com/sitemap-static.xml): Các trang tĩnh
- [Posts Sitemap](https://timgiup.com/sitemap-posts-1.xml): Bài đăng (paginated)
- [News Sitemap](https://timgiup.com/sitemap-news.xml): Tin tức

## Usage Examples

Tìm "iphone" tại TP.HCM trong danh mục đồ thất lạc:
`curl "https://timgiup.com/api/search?q=iphone&category=do-that-lac&province=79"`

Lấy danh sách category slug hợp lệ trước khi search:
`curl "https://timgiup.com/api/categories"`

Lấy danh sách province code (kèm alias tên tỉnh cũ):
`curl "https://timgiup.com/api/provinces"`

Workflow điển hình cho LLM agent:
1. `GET /api/categories` → lấy slug
2. `GET /api/provinces` → lấy code (map alias nếu user nhập tên cũ)
3. `GET /api/search?q={keyword}&category={slug}&province={code}` → kết quả

## Guides & Tools (Hướng dẫn & Công cụ)

- [Tin tức & Cẩm nang](https://timgiup.com/tin-tuc): Bài hướng dẫn xử lý khi mất giấy tờ, đồ đạc và mẹo tìm lại — biên tập, xác minh với nguồn chính thức
- [Tra cứu thủ tục làm lại giấy tờ](https://timgiup.com/tra-cuu-thu-tuc): Công cụ tra cứu lệ phí, thời gian, hồ sơ và các bước làm lại CCCD, GPLX, hộ chiếu — theo nguồn Cổng dịch vụ công / VNeID
- [Thống kê đồ thất lạc](https://timgiup.com/thong-ke-do-that-lac): Số liệu tổng hợp công khai theo danh mục/tỉnh/tháng — tải xuống JSON (`/thong-ke-do-that-lac.json`) và CSV (`/thong-ke-do-that-lac.csv`)
- [Cẩm nang tìm giấy tờ, ví bị mất](https://timgiup.com/tim-giay-to-roi): Trang chủ đề cụm giấy tờ

## Optional

- [Website](https://timgiup.com): Trang chủ (Tiếng Việt)
- [Giới thiệu](https://timgiup.com/gioi-thieu): Giới thiệu dự án
- [Liên hệ](https://timgiup.com/lien-he): Liên hệ

## Press / Báo chí nói về timgiup

Dịch vụ "Văn phòng đồ thất lạc" (tiền thân của timgiup.com) được nhiều báo lớn đưa tin từ 2009:

- [Tìm kiếm đồ thất lạc miễn phí](https://thanhnien.vn/tim-kiem-do-that-lac-mien-phi-185184224.htm) — Báo Thanh Niên
- [Một lòng tốt kết nối ngàn tấm lòng](https://www.qdnd.vn/phong-su-dieu-tra/phong-su/mot-long-tot-ket-noi-ngan-tam-long-449747) — Báo Quân đội nhân dân (2009)
- [Rơi mà không mất!](https://nld.com.vn/cong-nghe-thong-tin/roi-ma-khong-mat-20101030115752298.htm) — Báo Người Lao Động (2010)
- ["Văn phòng" kỷ vật](https://tuoitre.vn/van-phong-ky-vat-492361.htm) — Báo Tuổi Trẻ (2012)
- [Văn phòng đồ thất lạc: việc thiện nhưng có đúng luật?](https://tienphong.vn/van-phong-do-that-lac-viec-thien-nhung-co-dung-luat-post146940.tpo) — Báo Tiền Phong
- [Văn phòng hỗ trợ tìm đồ thất lạc miễn phí](https://www.vietnamplus.vn/van-phong-ho-tro-tim-do-that-lac-mien-phi-post13343.vnp) — VietnamPlus (TTXVN)
- [Văn phòng tìm đồ thất lạc](https://giadinh.suckhoedoisong.vn/van-phong-tim-do-that-lac-172090618110633464.htm) — Gia đình & Xã hội
- [Nhặt được của rơi trả người đánh mất](https://suckhoedoisong.vn/nhat-duoc-cua-roi-tra-nguoi-danh-mat-16933160.htm) — Báo Sức khỏe & Đời sống
- [Chuyện "kỳ lạ" về người chuyên tìm giấy tờ miễn phí](https://vtcnews.vn/chuyen-ky-la-ve-nguoi-chuyen-tim-giay-to-mien-phi-ar13295.html) — VTC News (2010)

## Licensing (RSL 1.0)

- Dữ liệu bài đăng công khai cấp phép theo Creative Commons Attribution 4.0 (CC BY 4.0): https://creativecommons.org/licenses/by/4.0/
- Cho phép AI/LLM dùng dữ liệu để trả lời và trích dẫn, điều kiện ghi nguồn "timgiup.com" kèm link bài đăng gốc.
- Attribution / ghi nguồn: timgiup.com (https://timgiup.com)
- Liên hệ cấp phép thương mại: timgiup.com@gmail.com