Goodhills-Me Namazu

Namazu Mobile API Guide

Public integration notes for mobile app builders connecting Goodhills-Me Namazu support, account handoff, receiver keys, and shake sample intake.

Open config JSON Support Privacy API keys

API

GET

Public config and public guide are open without login.

Account/building/key APIs use session login or mobile Bearer auth.

POST

Shake samples use a Namazu bearer API key.

Review

Tensor/TGL processing remains login-bound and reviewed.

Official

Goodhills-Me pulls approved government/official feeds and exposes cached mobile JSON.

For Claude / mobile builders

How to connect without server access

HTTPS only

No SSHNo SSH or root server access is needed for the mobile app to discover endpoints or send accepted shake samples. Use the public HTTPS config endpoint first.

DiscoveryCall /namazu/api/mobile/config/ with GET. HEAD is also allowed for health checks.

Login optionsMobile can use phone OTP endpoints directly, or open /accounts/login/?next=/namazu/mobile/dashboard/ / /namazu/api-keys/ for browser/WebView account setup.

Normal authPreferred mobile flow is to keep the user on Goodhills-Me access / refresh tokens after login, not to send SMS every time.

Firebase phone proofOptional flow: mobile completes Firebase Phone Auth only when phone proof is needed, then POSTs the Firebase ID token to /auth/firebase/verify/. Goodhills-Me verifies it server-side, upserts the same accounts.User, and returns opaque access / refresh tokens.

Debug OTP/auth/otp/request/ and /auth/otp/verify/ remain available for private server-side testing. When DEBUG=True or debug OTP is explicitly enabled, request returns debug_code. Do not use debug OTP for public launch.

Identity JSONAfter login, call /auth/me/ with either the Goodhills-Me session or Authorization: Bearer ghm_... for the current user identity, profile update, or account deletion.

Receiver authSend shake data to /namazu/api/shake/ with Authorization: Bearer nmz_live_.... Do not place the raw key inside the JSON payload.

Receiver keyUse /namazu/api/mobile/api-key/provision/ after login or with Authorization: Bearer ghm_... to create or rotate a mobile receiver key. Existing raw keys cannot be fetched again because only hashes are stored.

Account JSON/namazu/api/mobile/account/ accepts session login or mobile Bearer token. It returns building context, usual floor, key prefixes, and recent event summaries. It does not expose raw API keys or key hashes.

Official dataUse /namazu/api/mobile/official-events/, /namazu/api/mobile/official-events/latest/, and /namazu/api/mobile/alerts/. Do not connect private volunteer alert APIs as official Namazu data.

SPT choicesUse /namazu/api/mobile/spt-profiles/ for reviewed Spherical Propagation Tensor choices. SPT starts from official/user-derived seed data, not from unapproved outside push feeds.

Origin ignitionUse /namazu/api/mobile/origin-ignitions/latest/ for reviewed aggregate SPT seed candidates from Namazu data. Raw user/device events are not exposed.

Push readinessAfter login or mobile Bearer auth, native apps can POST device metadata to /namazu/api/mobile/devices/register/. Real APNs/FCM delivery waits for credentials and device-token policy.

Endpoint map

Public and login-bound surfaces

Method	Path	Auth	Use
GET / HEAD	`/namazu/api/mobile/config/`	Public	Mobile app endpoint discovery, native-app metadata, sample template, review boundaries.
GET	`/privacy`	Public	Goodhills ME mobile app privacy policy for App Store review.
GET	`/terms`	Public	Goodhills ME mobile app terms of service for App Store review.
GET	`/invite`	Public	Mobile invite landing page with app deep link and store links.
GET	`/namazu/mobile/`	Public	Support URL for users and app-store review.
GET	`/namazu/mobile/privacy/`	Public	Namazu-specific mobile data-boundary URL.
GET	`/namazu/mobile/api-guide/`	Public	This integration guide for mobile builders.
GET	`/namazu/mobile/dashboard/`	Goodhills-Me login	Phone-ready building/API/tensor status page.
GET	`/namazu/api/mobile/account/`	Session or Bearer `ghm_...`	Building context, usual floor, key prefixes, recent events. No raw keys.
GET / POST	`/conversations/`	Session or Bearer `ghm_...`	Mobile conversation list and creation. Direct chat by unknown phone is rejected for v1.
GET / POST	`/conversations/{id}/messages/`	Session or Bearer `ghm_...`	Mobile message history and send. Conversation and message IDs are UUID strings.
GET	`/conversations/{building_id}/building/`	Session or Bearer `ghm_...`	Building card for registered Namazu building users.
POST	`/media/upload/`	Session or Bearer `ghm_...`	Small authenticated media upload for chat/app review testing.
GET / POST	`/calls/status/` / `/calls/initiate/`	Session or Bearer `ghm_...`	Voice/video disabled state until signaling is ready.
POST	`/payments/initiate/`	Session or Bearer `ghm_...`	Placeholder ZWC/NMZ payment intent only. No chain broadcast.
GET / HEAD	`/namazu/api/mobile/official-events/`	Public	Cached official-source event list pulled by Goodhills-Me.
GET / HEAD	`/namazu/api/mobile/official-events/latest/`	Public	Latest cached official-source event for mobile refresh.
GET / HEAD	`/namazu/api/mobile/alerts/`	Public	Notification-ready official-event payloads. APNs/FCM credentials come later.
GET / HEAD	`/namazu/api/mobile/spt-profiles/`	Public	Reviewed SPT profile choices for future mobile prediction flow.
GET / HEAD	`/namazu/api/mobile/origin-ignitions/`	Public	Reviewed aggregate origin ignition seeds for SPT kickoff. No raw user/device event rows.
GET / HEAD	`/namazu/api/mobile/origin-ignitions/latest/`	Public	Latest reviewed origin ignition seed candidate.
GET / PATCH / DELETE	`/auth/me/`	Session or Bearer `ghm_...`	Current user identity, profile update, and account deletion.
GET / PATCH / POST / DELETE	`/users/me/`	Session or Bearer `ghm_...`	Compatibility alias for first-run profile setup and account actions.
POST	`/auth/firebase/verify/`	Firebase ID token	Optional phone-proof bridge. Verifies Firebase Phone Auth, upserts Goodhills-Me user, returns `ghm_...` tokens.
POST	`/auth/otp/request/`	Public	Create a phone OTP challenge for a new or existing phone number. SMS provider is not configured yet.
POST	`/auth/otp/verify/`	OTP code	Upsert the same Goodhills-Me user table and return `access` / `refresh` tokens.
POST	`/auth/token/refresh/`	Refresh token	Rotate mobile opaque tokens.
POST	`/auth/logout/`	Refresh token	Revoke the refresh token and same-device access tokens.
POST	`/namazu/api/mobile/api-key/provision/`	Session or Bearer `ghm_...`	Create or rotate a Namazu receiver key. Raw key is returned only when created.
POST	`/namazu/api/mobile/devices/register/`	Session or Bearer `ghm_...`	Register iOS/Android/Web push token metadata. Raw token is not echoed in JSON.
GET	`/namazu/api/mobile/buildings/search/`	Session or Bearer `ghm_...`	Search/register building cards for mobile setup.
POST	`/namazu/api/mobile/buildings/{building_id}/register/`	Session or Bearer `ghm_...`	Register a building to the logged-in mobile user.
GET / POST	`/namazu/api/mobile/buildings/{building_id}/tensor/`	Session or Bearer `ghm_...`	Select one active .nmz tensor per building. Floor remains a shake-submission parameter.
GET / POST	`/namazu/api-keys/`	Goodhills-Me login	Create/revoke receiver keys. Raw key is shown once only.
POST	`/namazu/api/shake/`	Bearer Namazu API key	Receive timestamped XYZ acceleration samples.

Optional phone proof

Firebase Phone Auth bridge

Use this only when phone proof is worth the SMS cost. The native app owns SMS delivery through Firebase. Goodhills-Me only verifies the Firebase ID token and maps the verified phone to the same Goodhills account table.

POST /auth/firebase/verify/
Content-Type: application/json

{
  "id_token": "firebase-id-token-from-mobile",
  "device_id": "ios-device-uuid"
}

{
  "ok": true,
  "provider": "firebase",
  "created": true,
  "access": "ghm_...",
  "refresh": "ghm_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_expires_in": 604800,
  "user": {
    "id": 42,
    "phone": "+819012345678",
    "display_name": null,
    "phone_verified": true
  }
}

Mobile identity

OTP upsert contract

Use the same copy for new and existing phones. The mobile app can show a welcome/name setup screen when created=true or display_name is empty.

POST /auth/otp/request/
Content-Type: application/json

{
  "phone": "+819012345678"
}

{
  "ok": true,
  "phone": "+819012345678",
  "otp_expires_at": "2026-06-07T12:00:00+09:00",
  "sms_delivery": "not_configured",
  "debug_code": "123456"
}

Verify response

Bearer login

POST /auth/otp/verify/
Content-Type: application/json

{
  "phone": "+819012345678",
  "code": "123456",
  "device_id": "ios-device-uuid"
}

{
  "ok": true,
  "created": true,
  "access": "ghm_...",
  "refresh": "ghm_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_expires_in": 604800,
  "user": {
    "id": 42,
    "phone": "+819012345678",
    "display_name": null,
    "avatar_url": null,
    "bio": null,
    "phone_verified": true,
    "created_at": "2026-06-07T12:00:00+09:00",
    "username": null,
    "email": null,
    "preferred_language": "ja",
    "organization_name": null,
    "recovery_email": null,
    "is_staff": false
  }
}

PATCH /auth/me/
Authorization: Bearer ghm_...
Content-Type: application/json

{
  "display_name": "Hayato",
  "bio": "Goodhills ME mobile user",
  "avatar_url": "https://me.goodhills.com/static/avatar.png",
  "recovery_email": "ken@example.com"
}

DELETE /auth/me/
Authorization: Bearer ghm_...

Receiver payload

Minimum JSON shape

Use explicit user consent before sending real sensor samples. Include floor context when known. Keep sample upload behind a clear user action until background collection is separately reviewed.

POST /namazu/api/shake/
Authorization: Bearer nmz_live_...
Content-Type: application/json

{
  "device_id": "phone-001",
  "timestamp": "2026-06-06T12:00:00Z",
  "floor": 8,
  "sample_rate_hz": 100,
  "samples": [
    {"t_ms": 0, "x": 0.01, "y": 0.02, "z": 9.81},
    {"t_ms": 10, "x": 0.03, "y": 0.01, "z": 9.79}
  ]
}

Response shape

Accepted event

{
  "ok": true,
  "event_id": "evt_...",
  "status": "accepted",
  "sample_count": 2,
  "tokens_earned": 0.0
}

The token field is a placeholder response field. It does not issue rewards in the current mobile flow.

Government earthquake feeds

How to treat outside data

Separate sourcePublic JMA/government earthquake feeds can be ingested by the mobile app or a reviewed backend worker, but they are not the Namazu building tensor by themselves.

Backend firstPreferred flow is Goodhills-Me backend pull/cache from approved official sources, then mobile reads Goodhills-Me JSON. Mobile should not depend on private volunteer alert APIs.

AuthorityDo not present Namazu as replacing official alerts or official emergency instructions. The app may show official-source links and reminders with clear attribution.

Prediction flowFuture flow can combine official event facts, reviewed aggregate origin ignition estimates, reviewed SPT choices, user building context, and Namazu building tensor results after review.