Skip to main content

Proximity Discovery

Proximity Discovery enables nodes to find other nodes based on geographic location. Unlike Account-Based Discovery, Proximity Discovery can discover nodes across accounts.

Prerequisites​

Proximity discovery requires a developer account and account association:

  1. Developer Console: Create a project and get your Client ID and Developer ID Token
  2. Account Association: Associate your mimOE node with your developer account to obtain an access token

The access token from account association is what you store via PUT /token in the API usage below.

Overview​

AttributeValue
ScopeGlobal (location-based)
Cloud dependencyRequires mDS (mimik Discovery Service)
CommunicationTunneled (HTTP only)
CapabilitiesHTTP RESTful APIs

How It Works​

Proximity Discovery uses mDS with geospatial indexing and IP-to-geolocation to enable location-based node discovery.

  1. Registration: Nodes register with mDS. By default, mDS uses the node's public IP for geolocation. If the node provides geographic coordinates (latitude, longitude, accuracy), those are used instead.

  2. Discovery: Applications query mDS with a location and radius. mDS returns nodes within the specified geographic area, sorted by distance.

  3. Communication: Discovered nodes communicate through the Tunneling Service, which handles NAT traversal.

API Usage​

Proximity discovery requires a stored JWT. First, store your access token with the Insight API:

curl -X PUT "http://localhost:8083/mimik-mesh/insight/v1/token" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "expiresAt": 1729677600
  }'

Then discover nearby nodes:

curl -X GET "http://localhost:8083/mimik-mesh/insight/v1/nodes?type=proximity" \
  -H "Authorization: Bearer $API_KEY"

Response (200 OK)

{
  "data": [
    {
      "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "accountId": "acct-789012",
      "name": "Nearby Node",
      "os": "android",
      "addresses": [
        {
          "type": "local",
          "url": { "href": "http://172.16.0.25:8083" }
        }
      ],
      "services": [
        {
          "id": "svc-002",
          "serviceType": "location-service-v1",
          "version": "1.0.0",
          "status": "running",
          "tenant": "default"
        }
      ]
    }
  ]
}

Discovered nodes communicate through tunneling. See Insight API: Tunneling via SEP for the routing workflow.

Use Cases​

  • Social applications: Find nearby users with similar interests
  • Location-based services: Discover local service providers
  • Autonomous mobility: Vehicle-to-vehicle communication and coordination
  • Retail: In-store navigation and location-based offers
  • Emergency services: Locate nearby first responders

Requirements​

  • Internet connectivity for mDS queries
  • Access token for mDS registration and queries
  • Device GPS or location services (optional, for more accurate positioning)

Limitations​

  • Requires internet connectivity for discovery
  • HTTP only for cross-network communication (no WebSocket/SSE yet)
  • Location accuracy depends on device GPS quality
  • Frequent location updates impact battery life

Privacy Considerations​

Applications using Proximity Discovery should:

  • Obtain explicit user consent before sharing location
  • Use the coarsest precision sufficient for the use case
  • Provide easy controls to disable location sharing
  • Comply with applicable privacy regulations (GDPR, CCPA)