apick-api 4.2.1 → 4.3.0

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+# 4.3.0
+
+- Add `createGoogleMapsPlaceJob(placeIdOrUrl)` with the `GoogleMapsPlace` result type: rating, reviews count, 1-5 star distribution, top reviews (up to 10), opening hours, busy hours, similar places and photos. 20 points per place, refunded if not found; text is returned in English.
+- 구글 지도 장소 상세·별점 분포·대표 리뷰(최대 10건) 조회 접수 메서드 `createGoogleMapsPlaceJob` 과 결과 타입 `GoogleMapsPlace` 를 추가했습니다. 건당 20포인트, 장소를 찾지 못하면 환불됩니다.
+
 # 4.2.1
 
 - `youtubeSubtitle()` fails with guidance to use an original-language track when an auto-translated caption (`translated: true`) is refused; such calls are not charged. Examples now pick a manual or original-language track. YouTube requests interrupted by a server restart are retried automatically.

package/README.md

@@ -99,6 +99,7 @@ Leave the allowed-IP list blank for unrestricted access. To restrict access, reg
 | `createTiktokVideoJob(url, options)` | 틱톡 영상 정보 접수 / TikTok video job | JSON |
 | `createTiktokCommentsJob(url, options)` | 틱톡 댓글 수집 접수(최대 100) / TikTok comments job | JSON |
 | `createAmazonReviewsJob(urlOrAsin, options)` | 아마존 리뷰 수집 접수(최대 100) / Amazon reviews job | JSON |
+| `createGoogleMapsPlaceJob(placeIdOrUrl, options)` | 구글 지도 장소 상세·별점 분포·대표 리뷰 접수 / Google Maps place details and top reviews job | JSON |
 | `getScrapeJob(jobId)` / `waitForScrapeJob(jobId, options)` | 수집 작업 상태·결과(무료, 결과 건수로 정산) / Collection job status and results | JSON |
 | `createTtsJob(text, options)` | 한국어 내레이션 작업 접수 / Create TTS job | JSON |
 | `getTtsJob(jobId)` | TTS 작업 상태 / TTS job status | JSON |

package/docs/guide.en.md

@@ -96,6 +96,15 @@ const done = await client.waitForScrapeJob(job.data.job_id); // every 10 s, up t
 console.log(done.data.status, done.data.charged_point, done.data.items);
 ```
 
+For a Google Maps place, pass the `place_id` from `googleMapsSearch` to get details, the star distribution and top reviews (up to 10). 20 points per place; text is returned in English.
+
+```js
+const places = await client.googleMapsSearch('cafes near Gangnam station');
+const placeJob = await client.createGoogleMapsPlaceJob(places.data.items[0].place_id);
+const place = await client.waitForScrapeJob(placeJob.data.job_id);
+console.log(place.data.items[0].rating_distribution, place.data.items[0].top_reviews);
+```
+
 ## OCR
 
 OCR accepts PNG and JPEG files up to 50MB.

package/docs/guide.ko.md

@@ -96,6 +96,15 @@ const done = await client.waitForScrapeJob(job.data.job_id); // 기본 10초 간
 console.log(done.data.status, done.data.charged_point, done.data.items);
 ```
 
+구글 지도 장소는 `googleMapsSearch` 결과의 `place_id` 로 상세·별점 분포·대표 리뷰(최대 10건)를 받습니다. 건당 20포인트이고 텍스트는 영어로 제공합니다.
+
+```js
+const places = await client.googleMapsSearch('강남역 카페');
+const placeJob = await client.createGoogleMapsPlaceJob(places.data.items[0].place_id);
+const place = await client.waitForScrapeJob(placeJob.data.job_id);
+console.log(place.data.items[0].rating_distribution, place.data.items[0].top_reviews);
+```
+
 ## OCR
 
 PNG와 JPEG를 지원하며 최대 크기는 50MB입니다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apick-api",
-  "version": "4.2.1",
+  "version": "4.3.0",
   "description": "Official zero-dependency Node.js client for APICK data, AI, and image APIs. 에이픽 데이터·AI·이미지 API 공식 Node.js SDK.",
   "type": "module",
   "main": "./src/index.cjs",

package/src/index.cjs

@@ -97,13 +97,19 @@ function profileInput(value) {
 	return /^https?:\/\//i.test(text) ? { url: text } : { username: text.replace(/^@/, '') };
 }
 
+// 구글 지도 장소 입력: 주소면 url, 아니면 place_id(googleMapsSearch 결과의 place_id)로 보낸다.
+function placeInput(value) {
+	const text = requiredString('placeIdOrUrl', value, 2048);
+	return /^https?:\/\//i.test(text) ? { url: text } : { place_id: text };
+}
+
 // 아마존 상품 입력: 주소면 url, 10자리 ASIN 이면 asin 으로 보낸다.
 function amazonInput(value) {
 	const text = requiredString('urlOrAsin', value, 2048);
 	return /^https?:\/\//i.test(text) ? { url: text } : { asin: text.toUpperCase() };
 }
 
-const SCRAPE_JOB_PRODUCTS = Object.freeze({ instagram_posts: 100, instagram_comments: 15, tiktok_search: 50, tiktok_video: 1, tiktok_comments: 100, amazon_reviews: 100 });
+const SCRAPE_JOB_PRODUCTS = Object.freeze({ instagram_posts: 100, instagram_comments: 15, tiktok_search: 50, tiktok_video: 1, tiktok_comments: 100, amazon_reviews: 100, google_maps_place: 1 });
 
 // 수집 작업 공통 옵션: maxResults(상품별 상한), idempotencyKey(응답을 못 받아 다시 보낼 때 같은 접수로 처리).
 function scrapeJobOptions(product, payload, options) {
@@ -708,6 +714,11 @@ class ApickClient {
 		return this._createScrapeJob('amazon_reviews', amazonInput(urlOrAsin), options);
 	}
 
+	// 구글 지도 장소 상세·대표 리뷰(건당 고정가). 텍스트는 영어로 온다.
+	createGoogleMapsPlaceJob(placeIdOrUrl, options) {
+		return this._createScrapeJob('google_maps_place', placeInput(placeIdOrUrl), options);
+	}
+
 	// 상태·결과 조회(무료). 끝난 작업은 실제 결과 건수로 정산돼 있다.
 	getScrapeJob(jobId) {
 		if (typeof jobId !== 'string' || !/^[a-f0-9]{32}$/.test(jobId)) throw new TypeError('jobId must be a 32-character job ID.');

package/src/index.d.ts

@@ -194,7 +194,37 @@ export interface AmazonReview {
 	readonly variant: string;
 }
 
-export type ScrapeJobProduct = "instagram_posts" | "instagram_comments" | "tiktok_search" | "tiktok_video" | "tiktok_comments" | "amazon_reviews";
+export interface GoogleMapsPlace {
+	readonly name: string;
+	readonly category: string;
+	readonly categories: readonly string[];
+	readonly address: string;
+	readonly country_code: string;
+	readonly phone: string;
+	readonly website: string;
+	readonly description: string;
+	readonly rating: number | null;
+	readonly reviews_count: number | null;
+	/** 별점별 리뷰 수. */
+	readonly rating_distribution: Readonly<Record<"1" | "2" | "3" | "4" | "5", number | null>>;
+	/** 대표 리뷰(최대 10건). 작성자는 공개 표시 이름만. */
+	readonly top_reviews: readonly { readonly reviewer_name: string; readonly rating: number | null; readonly posted_at: string; readonly text: string }[];
+	readonly open_hours: Readonly<Record<string, string>>;
+	/** day: 1=월 … 7=일 */
+	readonly popular_times: readonly { readonly day: number | null; readonly hours: readonly { readonly hour: string; readonly busy_percent: number | null }[] }[];
+	readonly similar_places: readonly { readonly name: string; readonly category: string; readonly rating: number | null; readonly reviews_count: number | null }[];
+	readonly photo_urls: readonly string[];
+	readonly main_image_url: string;
+	readonly is_claimed: boolean;
+	readonly permanently_closed: boolean;
+	readonly temporarily_closed: boolean;
+	readonly latitude: number | null;
+	readonly longitude: number | null;
+	readonly place_id: string;
+	readonly map_url: string;
+}
+
+export type ScrapeJobProduct = "instagram_posts" | "instagram_comments" | "tiktok_search" | "tiktok_video" | "tiktok_comments" | "amazon_reviews" | "google_maps_place";
 
 export interface ScrapeJobOptions {
 	/** 최대 결과 수. 이 수 × 단가를 예약하고 실제 결과 건수만 차감한다(instagram_comments 15, tiktok_search 50, 그 밖 100). */
@@ -624,6 +654,7 @@ export class ApickClient {
 	createTiktokVideoJob(url: string, options?: Pick<ScrapeJobOptions, "idempotencyKey">): Promise<ApickResult<ScrapeJob<TiktokVideo>>>;
 	createTiktokCommentsJob(url: string, options?: ScrapeJobOptions): Promise<ApickResult<ScrapeJob<SocialComment>>>;
 	createAmazonReviewsJob(urlOrAsin: string, options?: ScrapeJobOptions): Promise<ApickResult<ScrapeJob<AmazonReview>>>;
+	createGoogleMapsPlaceJob(placeIdOrUrl: string, options?: Pick<ScrapeJobOptions, "idempotencyKey">): Promise<ApickResult<ScrapeJob<GoogleMapsPlace>>>;
 	getScrapeJob<T = unknown>(jobId: string): Promise<ApickResult<ScrapeJob<T>>>;
 	waitForScrapeJob<T = unknown>(jobId: string, options?: { intervalMs?: number; timeoutMs?: number }): Promise<ApickResult<ScrapeJob<T>>>;
 	screenshot(url: string): Promise<ApickBinaryResult>;