Skill: sprintmint/cpbox-local-pois (version 1.0.0)

--- name: local-pois description: USE FOR getting local business/POI details. Requires POI IDs obtained from web-search (with result_filter=locations). Returns full business information including ratings, hours, contact info. Max 20 IDs. version: 1.0.0 --- # Local POIs (Search API) Paid Local POIs proxy via **x402 pay-per-use** (HTTP 402). > **Prerequisites**: This skill requires x402-payment. Complete the [setup steps](https://github.com/springmint/cpbox-skills#prerequisites) before first use. > > **Two-step flow**: This endpoint requires POI IDs from a prior web search. > > 1. Call `web-search` with `result_filter=locations` to get POI IDs from `locations.results[].id` > 2. Pass those IDs to this endpoint to get full business details > > **Security**: Documentation only — no executable code or credentials. Wallet/keys stay on your machine; never stored here. ## Service URLs | Role | Domain | |------|--------| | **API Provider** | https://www.cpbox.io | | **Facilitator** | https://www.cppay.finance | ## Endpoint (Agent Interface) ```http GET /api/x402/local-pois ``` ## Payment Flow (x402 Protocol) 1. **First request** -> `402 Payment Required` with requirements JSON 2. **Sign & retry** with `PAYMENT-SIGNATURE` -> result JSON With `@springmint/x402-payment` or `x402-sdk-go`, payment is **automatic**. ## Quick Start (cURL) ### Get POI Details ```bash curl -s "https://www.cpbox.io/api/x402/local-pois" \ -H "Accept: application/json" \ -H "Accept-Encoding: gzip" \ -G \ --data-urlencode [REDACTED_SECRET] ``` ### Multiple POIs with Location Headers ```bash curl -s "https://www.cpbox.io/api/x402/local-pois" \ -H "Accept: application/json" \ -H "Accept-Encoding: gzip" \ -H "X-Loc-Lat: 37.7749" \ -H "X-Loc-Long: -122.4194" \ -G \ --data-urlencode [REDACTED_SECRET] \ --data-urlencode [REDACTED_SECRET] \ --data-urlencode "units=imperial" ``` **Note**: POI IDs are opaque strings returned in web search `locations.results[].id`. IDs are ephemeral and expire after ~8 hours. The example IDs above are for illustration — fetch fresh IDs via `web-search` with `result_filter=locations`. Use `--data-urlencode` since IDs may contain `=`. ### POI ID Cache & Invalidation | Aspect | Policy | |--------|--------| | **TTL** | POI IDs are valid for approximately 8 hours from issuance. | | **Invalidation** | IDs cannot be refreshed or extended. After expiry, use `web-search` with `result_filter=locations` to obtain new IDs. | | **Caching** | You may cache POI details (hours, ratings, etc.) locally for display; do not cache IDs beyond 8 hours for reuse in `local-pois` or `local-descriptions`. | | **Expired ID** | Requests with expired IDs return empty or error results. Re-run the web search to get fresh IDs. | ## Using with x402-payment ```bash npx @springmint/x402-payment \ --url "https://www.cpbox.io/api/x402/local-pois?ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA%3D" \ --method GET ``` ## Parameters | Parameter | Type | Required | Default | Description | |--|--|--|--|--| | `ids` | string[] | **Yes** | — | POI IDs from web search results (1-20) | | `search_lang` | string | No | `en` | Language preference (2+ char language code) | | `ui_lang` | string | No | `en-US` | UI language (locale code, e.g., "en-US") | | `units` | string | No | null | `metric` (km) or `imperial` (miles) | ### Location Headers (Optional) For distance calculation from user location: | Header | Type | Range | Description | |--|--|--|--| | `X-Loc-Lat` | float | -90.0 to 90.0 | User latitude | | `X-Loc-Long` | float | -180.0 to 180.0 | User longitude | ## Response Fields The response has `type: "local_pois"` and a `results` array of `LocationResult` objects: | Field | Type | Description | |--|--|--| | `title` | string | Business/POI name | | `url` | string | Canonical URL for the location | | `provider_url` | string | Provider page URL | | `type` | string | Always `"location_result"` | | `id` | string | POI identifier (opaque string, valid ~8 hours) | | `description` | string? | Short description | | `postal_address.type` | string | Always `"PostalAddress"` | | `postal_address.displayAddress` | string | Formatted display address | | `postal_address.streetAddress` | string? | Street address | | `postal_address.addressLocality` | string? | City | | `postal_address.addressRegion` | string? | State/region | | `postal_address.postalCode` | string? | Postal/ZIP code | | `postal_address.country` | string? | Country code | | `contact.telephone` | string? | Phone number | | `contact.email` | string? | Email address | | `rating.ratingValue` | float? | Average rating (≥0) | | `rating.bestRating` | float? | Max possible rating | | `rating.reviewCount` | int? | Number of reviews | | `rating.profile.name` | string? | Rating provider name | | `rating.profile.url` | string? | Rating provider URL | | `opening_hours.current_day` | object[]? | Today's hours (`abbr_name`, `full_name`, `opens`, `closes`) | | `opening_hours.days` | object[][]? | Hours for each day of the week (same structure) | | `coordinates` | [float, float]? | `[latitude, longitude]` tuple | | `distance.value` | float? | Distance from user location | | `distance.units` | string? | Distance unit (`km` or `miles`) | | `categories` | string[] | Business categories (default `[]`) | | `price_range` | string? | Price indicator (`$`, `$$`, `$$$`, `$$$$`) | | `serves_cuisine` | string[]? | Cuisine types (restaurants) | | `thumbnail.src` | string? | Thumbnail image URL | | `thumbnail.original` | string? | Original image URL | | `profiles` | object[]? | External profiles (`name`, `url`, `long_name`, `img`) | | `reviews.reviews_in_foreign_language` | bool | Whether reviews in a foreign language are available | | `pictures.results` | object[]? | Photo thumbnails | | `action` | object? | Action to take — has `type` (string) and `url` (string) | | `results` | object[]? | Related web results (`LocationWebResult` with `meta_url`) | | `timezone` | string? | IANA timezone (e.g., `America/Los_Angeles`) | | `timezone_offset` | int? | UTC timezone offset | ### Example Response ```json { "type": "local_pois", "results": [ { "type": "location_result", "title": "Park Mediterranean Grill", "url": "https://yelp.com/biz/park-mediterranean-grill-sf", "provider_url": "https://yelp.com/biz/park-mediterranean-grill-sf", "id": [REDACTED_SECRET], "postal_address": { "type": "PostalAddress", "displayAddress": "123 Main St, San Francisco, CA 94102", "streetAddress": "123 Main St", "addressLocality": "San Francisco", "addressRegion": "CA", "postalCode": "94102", "country": "US" }, "contact": { "telephone": "+1 415-555-0123" }, "thumbnail": { "src": "https://example.com/thumb.jpg", "original": "https://example.com/original.jpg" }, "rating": { "ratingValue": 4.5, "bestRating": 5.0, "reviewCount": 234, }, "opening_hours": { "current_day": [ { "abbr_name": "Mon", "full_name": "Monday", "opens": "07:00", "closes": "21:00" } ] }, "coordinates": [37.7749, -122.4194], "distance": { "value": 0.3, "units": "miles" }, "categories": ["Mediterranean", "Greek"], "price_range": "$$", "serves_cuisine": ["Mediterranean", "Greek"], "timezone": "America/Los_Angeles" } ] } ``` ## Getting POI IDs POI IDs come from the **Web Search API** (`web-search`) with `result_filter=locations`: ```bash # 1. Search for local businesses curl -s "https://www.cpbox.io/api/x402/web-search?q=coffee+shops+near+me&result_filter=locations" \ -H "Accept: application/json" \ -H "X-Loc-Lat: 37.7749" \ -H "X-Loc-Long: -122.4194" # 2. Extract POI IDs from locations.results[].id # 3. Use those IDs with this endpoint ``` ## Use Cases - **Local business lookup**: Retrieve full details (hours, contact, address) for POIs surfaced in web search - **Restaurant discovery pipeline**: Search for restaurants, fetch POI details, filter by cuisine/rating/price_range - **Business hours checker**: Get opening_hours for a business to determine if currently open - **Location-aware application**: Combine with location headers to get distance calculations for nearby POIs ## Notes - **ID format**: Opaque strings (use `--data-urlencode` for cURL) - **Units**: `metric` or `imperial` for distance measurement preference - **Max IDs**: Up to 20 IDs per request


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)