Martech & SEO Platform
Radius - Spatial Rank Tracking & Hyper-Local Diagnostics
Deterministic geospatial rank tracking API measuring Google Maps visibility per coordinate across calibrated walking perimeters.
POST
/
api
/
v1
/
spatial
/
analyze
Radius - Spatial Rank Tracking & Hyper-Local Diagnostics
curl --request POST \
--url https://radius-api.ypym.app/api/v1/spatial/analyze \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"keyword": "<string>",
"center_lat": 123,
"center_lng": 123,
"country_code": "<string>",
"language_code": "<string>",
"grid_size": 123,
"step_meters": 123,
"s2_level": 123,
"target_entity": {
"target_entity.brand_name": "<string>",
"target_entity.auto_discover_missing": true
}
}
'import requests
url = "https://radius-api.ypym.app/api/v1/spatial/analyze"
payload = {
"keyword": "<string>",
"center_lat": 123,
"center_lng": 123,
"country_code": "<string>",
"language_code": "<string>",
"grid_size": 123,
"step_meters": 123,
"s2_level": 123,
"target_entity": {
"target_entity.brand_name": "<string>",
"target_entity.auto_discover_missing": True
}
}
headers = {
"Authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
keyword: '<string>',
center_lat: 123,
center_lng: 123,
country_code: '<string>',
language_code: '<string>',
grid_size: 123,
step_meters: 123,
s2_level: 123,
target_entity: {
'target_entity.brand_name': '<string>',
'target_entity.auto_discover_missing': true
}
})
};
fetch('https://radius-api.ypym.app/api/v1/spatial/analyze', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://radius-api.ypym.app/api/v1/spatial/analyze",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'keyword' => '<string>',
'center_lat' => 123,
'center_lng' => 123,
'country_code' => '<string>',
'language_code' => '<string>',
'grid_size' => 123,
'step_meters' => 123,
's2_level' => 123,
'target_entity' => [
'target_entity.brand_name' => '<string>',
'target_entity.auto_discover_missing' => true
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://radius-api.ypym.app/api/v1/spatial/analyze"
payload := strings.NewReader("{\n \"keyword\": \"<string>\",\n \"center_lat\": 123,\n \"center_lng\": 123,\n \"country_code\": \"<string>\",\n \"language_code\": \"<string>\",\n \"grid_size\": 123,\n \"step_meters\": 123,\n \"s2_level\": 123,\n \"target_entity\": {\n \"target_entity.brand_name\": \"<string>\",\n \"target_entity.auto_discover_missing\": true\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://radius-api.ypym.app/api/v1/spatial/analyze")
.header("Authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"keyword\": \"<string>\",\n \"center_lat\": 123,\n \"center_lng\": 123,\n \"country_code\": \"<string>\",\n \"language_code\": \"<string>\",\n \"grid_size\": 123,\n \"step_meters\": 123,\n \"s2_level\": 123,\n \"target_entity\": {\n \"target_entity.brand_name\": \"<string>\",\n \"target_entity.auto_discover_missing\": true\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://radius-api.ypym.app/api/v1/spatial/analyze")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"keyword\": \"<string>\",\n \"center_lat\": 123,\n \"center_lng\": 123,\n \"country_code\": \"<string>\",\n \"language_code\": \"<string>\",\n \"grid_size\": 123,\n \"step_meters\": 123,\n \"s2_level\": 123,\n \"target_entity\": {\n \"target_entity.brand_name\": \"<string>\",\n \"target_entity.auto_discover_missing\": true\n }\n}"
response = http.request(request)
puts response.read_body{
"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"
}

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
Test live storefront presets, inspect interactive radar maps, and experiment in your browser at radius.ypym.app
Product Overview & Pricing
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 theAuthorization HTTP header:
Authorization: Bearer ypym_radius_demo_9876543210abcdef
ypym_radius_demo_9876543210abcdef (or alias ypym_radius_demo_code).

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
string
default:"Bearer ypym_radius_demo_9876543210abcdef"
required
Bearer token for API gateway authentication.
string
default:"cafe di araya malang"
required
The target local search query to audit on Google Maps (e.g.
cafe terdekat, resto 24 jam, coffee shop near me).number
default:-7.9405
required
Latitude coordinate of the storefront centroid or search origin (e.g.
-7.9405).number
default:112.6565
required
Longitude coordinate of the storefront centroid or search origin (e.g.
112.6565).string
default:"id"
Two-letter ISO 3166-1 alpha-2 country code (default:
id).string
default:"en"
ISO 639-1 language code for localized search results (default:
en).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).number
default:500
Step distance between radial calculation rings in meters (default:
500).integer
default:14
Google S2 Cell spherical projection hierarchy level (default:
14, approximately ~600m centroid diameter).object
Configuration object for canonical brand matching and candidate identification.
Response Schema
{
"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)
- cURL / REST API
- Python
- Go (Golang)
- PHP (Laravel)
- Postman
Install the official client package:Execute a 5-perimeter spatial audit:
npm install ypym-radius
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);
Run directly from your command line:
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
}
}'
Call via the standard
requests library: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())
High-performance native Go 1.22+ client:
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))
}
Integration via Laravel HTTP facade:
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);
You can test and import the collection directly into Postman:
- Method & URL:
POST https://radius-api.ypym.app/api/v1/spatial/analyze - Authorization: Tab
Authorization→ TypeBearer Token→ Token:ypym_radius_demo_9876543210abcdef - Headers:
Content-Type: application/json - Body: Select
raw→JSON, paste the request payload above.
Token Quota & Wallet Introspection
To check remaining API credits and verify token health before initiating batch auditing pipelines, query the/wallet endpoint:
curl -s -X GET "https://radius-api.ypym.app/api/v1/wallet" \
-H "Authorization: Bearer ypym_radius_demo_9876543210abcdef"
{
"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
Test real-world storefront presets (Malang, Bandung, Jakarta) or input your own coordinates at radius.ypym.app
⌘I
Radius - Spatial Rank Tracking & Hyper-Local Diagnostics
curl --request POST \
--url https://radius-api.ypym.app/api/v1/spatial/analyze \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"keyword": "<string>",
"center_lat": 123,
"center_lng": 123,
"country_code": "<string>",
"language_code": "<string>",
"grid_size": 123,
"step_meters": 123,
"s2_level": 123,
"target_entity": {
"target_entity.brand_name": "<string>",
"target_entity.auto_discover_missing": true
}
}
'import requests
url = "https://radius-api.ypym.app/api/v1/spatial/analyze"
payload = {
"keyword": "<string>",
"center_lat": 123,
"center_lng": 123,
"country_code": "<string>",
"language_code": "<string>",
"grid_size": 123,
"step_meters": 123,
"s2_level": 123,
"target_entity": {
"target_entity.brand_name": "<string>",
"target_entity.auto_discover_missing": True
}
}
headers = {
"Authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
keyword: '<string>',
center_lat: 123,
center_lng: 123,
country_code: '<string>',
language_code: '<string>',
grid_size: 123,
step_meters: 123,
s2_level: 123,
target_entity: {
'target_entity.brand_name': '<string>',
'target_entity.auto_discover_missing': true
}
})
};
fetch('https://radius-api.ypym.app/api/v1/spatial/analyze', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://radius-api.ypym.app/api/v1/spatial/analyze",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'keyword' => '<string>',
'center_lat' => 123,
'center_lng' => 123,
'country_code' => '<string>',
'language_code' => '<string>',
'grid_size' => 123,
'step_meters' => 123,
's2_level' => 123,
'target_entity' => [
'target_entity.brand_name' => '<string>',
'target_entity.auto_discover_missing' => true
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://radius-api.ypym.app/api/v1/spatial/analyze"
payload := strings.NewReader("{\n \"keyword\": \"<string>\",\n \"center_lat\": 123,\n \"center_lng\": 123,\n \"country_code\": \"<string>\",\n \"language_code\": \"<string>\",\n \"grid_size\": 123,\n \"step_meters\": 123,\n \"s2_level\": 123,\n \"target_entity\": {\n \"target_entity.brand_name\": \"<string>\",\n \"target_entity.auto_discover_missing\": true\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://radius-api.ypym.app/api/v1/spatial/analyze")
.header("Authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"keyword\": \"<string>\",\n \"center_lat\": 123,\n \"center_lng\": 123,\n \"country_code\": \"<string>\",\n \"language_code\": \"<string>\",\n \"grid_size\": 123,\n \"step_meters\": 123,\n \"s2_level\": 123,\n \"target_entity\": {\n \"target_entity.brand_name\": \"<string>\",\n \"target_entity.auto_discover_missing\": true\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://radius-api.ypym.app/api/v1/spatial/analyze")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"keyword\": \"<string>\",\n \"center_lat\": 123,\n \"center_lng\": 123,\n \"country_code\": \"<string>\",\n \"language_code\": \"<string>\",\n \"grid_size\": 123,\n \"step_meters\": 123,\n \"s2_level\": 123,\n \"target_entity\": {\n \"target_entity.brand_name\": \"<string>\",\n \"target_entity.auto_discover_missing\": true\n }\n}"
response = http.request(request)
puts response.read_body{
"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"
}