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 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#

RoleDomainAPI Providerhttps://www.cpbox.ioFacilitatorhttps://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 "ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA="

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 "ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=" \
  --data-urlencode "ids=loc4HTAVTJKP4RBEBZCEMBI3NG26YD4II4PATIHPDYI=" \
  --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#

AspectPolicyTTLPOI IDs are valid for approximately 8 hours from issuance.InvalidationIDs cannot be refreshed or extended. After expiry, use web-search with result_filter=locations to obtain new IDs.CachingYou 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 IDRequests 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#

ParameterTypeRequiredDefaultDescriptionidsstring[]Yes—POI IDs from web search results (1-20)search_langstringNoenLanguage preference (2+ char language code)ui_langstringNoen-USUI language (locale code, e.g., "en-US")unitsstringNonullmetric (km) or imperial (miles)

Location Headers (Optional)#

For distance calculation from user location:

HeaderTypeRangeDescriptionX-Loc-Latfloat-90.0 to 90.0User latitudeX-Loc-Longfloat-180.0 to 180.0User longitude

Response Fields#

The response has type: "local_pois" and a results array of LocationResult objects:

FieldTypeDescriptiontitlestringBusiness/POI nameurlstringCanonical URL for the locationprovider_urlstringProvider page URLtypestringAlways "location_result"``idstringPOI identifier (opaque string, valid ~8 hours)descriptionstring?Short descriptionpostal_address.typestringAlways "PostalAddress"``postal_address.displayAddressstringFormatted display addresspostal_address.streetAddressstring?Street addresspostal_address.addressLocalitystring?Citypostal_address.addressRegionstring?State/regionpostal_address.postalCodestring?Postal/ZIP codepostal_address.countrystring?Country codecontact.telephonestring?Phone numbercontact.emailstring?Email addressrating.ratingValuefloat?Average rating (≥0)rating.bestRatingfloat?Max possible ratingrating.reviewCountint?Number of reviewsrating.profile.namestring?Rating provider namerating.profile.urlstring?Rating provider URLopening_hours.current_dayobject[]?Today's hours ( abbr_name, full_name, opens, closes)opening_hours.daysobject[][]?Hours for each day of the week (same structure)coordinates[float, float]?[latitude, longitude] tupledistance.valuefloat?Distance from user locationdistance.unitsstring?Distance unit ( km or miles)categoriesstring[]Business categories (default [])price_rangestring?Price indicator ( $, $$, $$$, $$$$)serves_cuisinestring[]?Cuisine types (restaurants)thumbnail.srcstring?Thumbnail image URLthumbnail.originalstring?Original image URLprofilesobject[]?External profiles ( name, url, long_name, img)reviews.reviews_in_foreign_languageboolWhether reviews in a foreign language are availablepictures.resultsobject[]?Photo thumbnailsactionobject?Action to take — has type (string) and url (string)resultsobject[]?Related web results ( LocationWebResult with meta_url)timezonestring?IANA timezone (e.g., America/Los_Angeles)timezone_offsetint?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": "loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=",
      "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