> ## Documentation Index
> Fetch the complete documentation index at: https://hub.ypym.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Radius - Spatial Rank Tracking & Hyper-Local Diagnostics

> Deterministic geospatial rank tracking API measuring Google Maps visibility per coordinate across calibrated walking perimeters.

![Radius logo](https://mintcdn.com/ypymcompany/XP0cPmv0arvMrg_c/images/products/radius.png?fit=max\&auto=format\&n=XP0cPmv0arvMrg_c\&q=85\&s=21d1c67a84de81345e8b9aa56caf08de)

## Overview

**YPYM Radius** is our deterministic spatial rank diagnostics and hyper-local search visibility engine. Standard rank-tracking tools measure search performance from single, centralized synthetic proxy endpoints, completely missing the micro-variations that occur across neighborhoods, postal codes, and physical walking perimeters.

Radius solves this blind spot by executing coordinate diagnostics across distributed Google S2 spherical cell matrices, calculating precise visibility radii (50m, 100m, 200m, 500m, and 1,000m), local 3-pack presence, and competitor displacement in sub-second latency.

> **[Live Interactive Playground](https://radius.ypym.app)**
>
> Test live storefront presets, inspect interactive radar maps, and experiment in your browser at radius.ypym.app

> **[Product Overview & Pricing](https://suite.ypym.app/radius)**
>
> Explore enterprise methodology, multi-location case studies, and tier pricing at suite.ypym.app/radius

***

## Authentication & Sandbox Token

Every request to the Radius REST API Gateway requires a valid Bearer token passed in the `Authorization` HTTP header:

```http theme={null}
Authorization: Bearer ypym_radius_demo_9876543210abcdef
```

For sandbox testing and immediate evaluation, use the pre-provisioned demo key:
`ypym_radius_demo_9876543210abcdef` (or alias `ypym_radius_demo_code`).

![Radius Spatial Rank Diagnostics API Tested on Postman](https://mintcdn.com/ypymcompany/uCNaM1iiG0xV0C9_/images/radius-api-postman-suite.jpg?fit=max\&auto=format\&n=uCNaM1iiG0xV0C9_\&q=85\&s=9731f8da62931417b82dcffb51a7d19d)

Direct Postman API execution testing the YPYM Radius endpoint (POST /api/v1/spatial/analyze) against mining enterprise entity PT KALTIM PRIMA COAL. The JSON payload returns HTTP 200 OK in 648 ms via the S2X Spatial MTPET pipeline, validating a weighted proximity score of 100 alongside dominant Google S2 spherical cell identifiers (320a35c3, 320a35ef) for deterministic local visibility benchmarking.

***

## Request Parameters

**Authorization** `string` *required* (default: Bearer ypym\_radius\_demo\_9876543210abcdef)

Bearer token for API gateway authentication.

**keyword** `string` *required* (default: cafe di araya malang)

The target local search query to audit on Google Maps (e.g. `cafe terdekat`, `resto 24 jam`, `coffee shop near me`).

**center\_lat** `number` *required* (default: -7.9405)

Latitude coordinate of the storefront centroid or search origin (e.g. `-7.9405`).

**center\_lng** `number` *required* (default: 112.6565)

Longitude coordinate of the storefront centroid or search origin (e.g. `112.6565`).

**country\_code** `string` (default: id)

Two-letter ISO 3166-1 alpha-2 country code (default: `id`).

**language\_code** `string` (default: en)

ISO 639-1 language code for localized search results (default: `en`).

**grid\_size** `integer` (default: 1)

Centroid matrix dimension. Use `1` for single-centroid 5-perimeter audits, or `3`, `5`, `7` for multi-cell spatial grid coverage (must be odd numbers).

**step\_meters** `number` (default: 500)

Step distance between radial calculation rings in meters (default: `500`).

**s2\_level** `integer` (default: 14)

Google S2 Cell spherical projection hierarchy level (default: `14`, approximately \~600m centroid diameter).

**target\_entity** `object`

Configuration object for canonical brand matching and candidate identification.

**properties**

**target\_entity.brand\_name** `string` (default: Starbucks)

Canonical business or brand name to track across radial rings.

**target\_entity.auto\_discover\_missing** `boolean` (default: true)

Automatically discover competing candidate profiles when the target brand is displaced from top Local 3-Pack rankings.

***

## Response Schema

```json theme={null}
{
  "status": "success",
  "audit_timestamp": "2026-10-12T01:38:00Z",
  "request_centroid": {
    "lat": -7.9405,
    "lng": 112.6565,
    "keyword": "cafe di araya malang",
    "s2_level": 14
  },
  "brand_ranking": {
    "target_brand": "Starbucks",
    "ranks": {
      "50m": "#1",
      "100m": "#1",
      "200m": "#1",
      "500m": "#2",
      "1000m": "#4"
    },
    "visibility_status": "Local 3-Pack Leader"
  },
  "top_competitors": [
    { "rank": 2, "name": "Niko Cafe Araya", "distance": "75m away" },
    { "rank": 3, "name": "Kopi Kenangan Araya", "distance": "140m away" },
    { "rank": 4, "name": "Janji Jiwa Blimbing", "distance": "220m away" }
  ],
  "credits_charged": 5,
  "idempotency_key": "ypym_rad_9876543210_araya"
}
```

***

## Quickstart Implementations

**Node.js (NPM)**

Install the official client package:

```bash theme={null}
npm install ypym-radius
```

Execute a 5-perimeter spatial audit:

```typescript theme={null}
import { RadiusClient } from 'ypym-radius';

const radius = new RadiusClient({
  apiKey: 'ypym_radius_demo_9876543210abcdef'
});

const result = await radius.auditSERP({
  query: 'cafe di araya malang',
  latitude: -7.9405,
  longitude: 112.6565,
  targetBrand: 'Starbucks'
});

console.log(result.ranks, result.topCompetitors);
```

**cURL / REST API**

Run directly from your command line:

```bash theme={null}
curl -X POST "https://radius-api.ypym.app/api/v1/spatial/analyze" \
  -H "Authorization: Bearer ypym_radius_demo_9876543210abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "cafe di araya malang",
    "center_lat": -7.9405,
    "center_lng": 112.6565,
    "grid_size": 1,
    "step_meters": 500,
    "s2_level": 14,
    "target_entity": {
      "brand_name": "Starbucks",
      "auto_discover_missing": true
    }
  }'
```

**Python**

Call via the standard `requests` library:

```python theme={null}
import requests

headers = {
    "Authorization": "Bearer ypym_radius_demo_9876543210abcdef",
    "Content-Type": "application/json"
}

payload = {
    "keyword": "cafe di araya malang",
    "center_lat": -7.9405,
    "center_lng": 112.6565,
    "grid_size": 1,
    "step_meters": 500,
    "s2_level": 14,
    "target_entity": {
        "brand_name": "Starbucks",
        "auto_discover_missing": True
    }
}

response = requests.post(
    "https://radius-api.ypym.app/api/v1/spatial/analyze",
    json=payload,
    headers=headers
)

print(response.json())
```

**Go (Golang)**

High-performance native Go 1.22+ client:

```go theme={null}
package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
)

func main() {
  body := []byte(`{
    "keyword": "cafe di araya malang",
    "center_lat": -7.9405,
    "center_lng": 112.6565,
    "grid_size": 1,
    "step_meters": 500,
    "s2_level": 14,
    "target_entity": {"brand_name": "Starbucks"}
  }`)

  req, _ := http.NewRequest("POST", "https://radius-api.ypym.app/api/v1/spatial/analyze", bytes.NewBuffer(body))
  req.Header.Set("Authorization", "Bearer ypym_radius_demo_9876543210abcdef")
  req.Header.Set("Content-Type", "application/json")

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  res, _ := io.ReadAll(resp.Body)
  fmt.Println(string(res))
}
```

**PHP (Laravel)**

Integration via Laravel HTTP facade:

```php theme={null}
use Illuminate\Support\Facades\Http;

$response = Http::withToken('ypym_radius_demo_9876543210abcdef')
  ->post('https://radius-api.ypym.app/api/v1/spatial/analyze', [
    'keyword' => 'cafe di araya malang',
    'center_lat' => -7.9405,
    'center_lng' => 112.6565,
    'grid_size' => 1,
    'step_meters' => 500,
    's2_level' => 14,
    'target_entity' => [
      'brand_name' => 'Starbucks',
      'auto_discover_missing' => true,
    ],
  ]);

$data = $response->json();
print_r($data);
```

**Postman**

You can test and import the collection directly into Postman:

1. **Method & URL**: `POST https://radius-api.ypym.app/api/v1/spatial/analyze`
2. **Authorization**: Tab `Authorization` → Type `Bearer Token` → Token: `ypym_radius_demo_9876543210abcdef`
3. **Headers**: `Content-Type: application/json`
4. **Body**: Select `raw` → `JSON`, paste the request payload above.

Download the pre-configured Postman collection directly from our live console at [radius.ypym.app#developer](https://radius.ypym.app#developer).

***

## Token Quota & Wallet Introspection

To check remaining API credits and verify token health before initiating batch auditing pipelines, query the `/wallet` endpoint:

```bash theme={null}
curl -s -X GET "https://radius-api.ypym.app/api/v1/wallet" \
  -H "Authorization: Bearer ypym_radius_demo_9876543210abcdef"
```

**Response**:

```json theme={null}
{
  "org_id": "org_demo_developer_01",
  "balance_credits": 500,
  "reserved_credits": 0,
  "total_consumed_credits": 0,
  "updated_at": "2026-10-12T01:25:20Z"
}
```

***

## Key Enterprise Use Cases

| Industry / Application | Strategic Focus |
| - | - |
| **Multi-Branch Retail & F\&B** | Measuring real visibility across dense urban districts and delivery coverage zones |
| **Healthcare & Clinics** | Diagnosing catchment area reach and organic patient acquisition radius |
| **Banking & Financial Centers** | Auditing local search dominance across branch networks and automated teller points |
| **Real Estate & Developments** | Tracking local search capture around emerging property developments and regional hubs |

***

## Engagement & Production Provisioning

> **[Start Exploring on Radius Playground](https://radius.ypym.app)**
>
> Test real-world storefront presets (Malang, Bandung, Jakarta) or input your own coordinates at radius.ypym.app


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.