Stateful Navigation API (Split Audio/Data + Integrated Milestones)

Step 1: Upload Query Audio

POST /upload_audio

Uploads the user's spoken destination query.

Input

• Header: Authentication: YOUR_USER_ID
• Body: Raw binary audio data.

Output (JSON)

{ "status": "AudioReceived", "upload_id": "up_..." }

Save the `upload_id`.

Step 2: Send Location for Query

POST /process_query_location

Processes the query using the uploaded audio and location. Fetches milestones if navigation starts.

Input (application/json)

{
    "upload_id": "up_...", // From Step 1
    "latitude": float,
    "longitude": float,
    "heading": float // Optional
}

Output (JSON) - Key Scenarios

• Status: "AwaitingSelection"
  • POI options found. Play audio_response_b64 or use TTS on prompt_text.
  • Save state_id (e.g., `poi_...`) for Step 4.
• Status: "NavigationStarted"
  • Direct navigation begins.
  • Play initial_audio_steps_b64 list or use TTS on initial_steps_text list (first few steps, may include milestone announcements at the start).
  • Save navigation_session_id (e.g., `nav_...`) for Step 5 onwards.
• Status: "Error" (4xx/5xx)
  • Play audio_response_b64 or use TTS on error_message.

Step 3: Upload Selection Audio

POST /upload_audio

Uploads the user's spoken POI option number.

Input

• Header: Authentication: YOUR_USER_ID
• Body: Raw binary audio data.

Output (JSON)

{ "status": "AudioReceived", "upload_id": "up_..." }

Save the NEW `upload_id`.

Step 4: Send Selection Context

POST /process_selection_location

Processes the selection, starts navigation, and fetches milestones.

Input (application/json)

{
    "upload_id": "up_...", // From Step 3
    "state_id": "poi_..."  // From Step 2
}

Output (JSON) - Key Scenarios

• Status: "NavigationStarted"
  • POI selected. Navigation begins.
  • Play initial_audio_steps_b64 list or use TTS on initial_steps_text list (first few steps, may include milestone announcements at the start).
  • Save navigation_session_id (e.g., `nav_...`) for Step 5 onwards.
• Status: "Error" (4xx/5xx)
  • Selection failed. Play audio_response_b64 or use TTS on error_message.
  • May return original state_id for retry of Steps 3 & 4.

Step 5: Get Next Steps (Repeat with Smart Logic + Integrated Milestones)

POST /get_next_steps

Call periodically (e.g., every 5-10s). Server checks proximity to next turn AND nearby milestones, returning relevant instructions only.

Input: application/json

{
    "navigation_session_id": "nav_...", // Session ID from Step 2 or 4
    "latitude": CURRENT_LATITUDE,
    "longitude": CURRENT_LONGITUDE,
    "heading": CURRENT_HEADING // Optional
}

Output (JSON) - Key Scenarios (200 OK)

• Status: "NextSteps"
  • Condition: User near next maneuver OR time threshold met.
  • Action: Play audio_steps_b64 list or use TTS on steps_text list. Nearby milestone announcements (e.g., "Park Gate ahead.") will be included as items at the beginning of these lists if applicable.
  • Repeat Step 5.
• Status: "ApproachingDestination"
  • Condition: Same as "NextSteps", but batch includes arrival step.
  • Action: Play audio_steps_b64 / use TTS on steps_text. Milestone announcements may be prepended.
  • Repeat Step 5 (optional).
• Status: "OnRoute"
  • Condition: No new navigation step needed yet.
  • Action: Play optional audio_message_b64 or use TTS on message. This message will include nearby milestone announcements prepended if applicable (e.g., "Library to your right. Continue. Next turn in 80 meters.").
  • Repeat Step 5.
• Status: "Arrived"
  • Condition: Server determines arrival.
  • Action: Play audio_message_b64 OR use TTS on message.
  • Stop calling this endpoint.
• Status: "Error" (4xx/5xx)
  • Condition: Session invalid, internal error, etc.
  • Action: Use TTS on error_message.
  • Stop calling this endpoint.

Milestone announcements are now part of the main audio/text fields, not a separate list.

Text POI Search

POST /search_poi

(Stateless) Input JSON: {"query", "latitude", "longitude"}. Returns JSON: {"status":"ok", "results": [...]}.

Start Text Navigation

POST /navigate

(Starts stateful session) Input JSON: {"destination_query", ...}. Returns JSON: {"status":"NavigationStarted", "navigation_session_id", ...}. Use `/get_next_steps` to continue.

API Documentation

GET /

Returns this HTML documentation.