API Reference

This section provides detailed information about the API endpoints for the Health Recommendation System.

Health Recommendations

POST /recommend

Generate a health service recommendation based on the input query.

Request Body

{
   "query": "I need mental health support",
   "latitude": 43.6532,
   "longitude": -79.3832,
   "radius": 5000,
   "rerank": false
}

Request JSON Object:

• query (string) – The user’s health-related query (required)

• latitude (number) – Optional latitude for location-based search

• longitude (number) – Optional longitude for location-based search

• radius (number) – Optional search radius in meters (default: 5000)

• rerank (boolean) – Optional flag to enable/disable reranking of the services (default: false)

Response JSON Object:

• recommendation (string) – Generated recommendation text

• services (array) – List of relevant health services

Response Body

{
   "message": "Based on your query...",
   "is_emergency": false,
   "is_out_of_scope": false,
   "services": [
      {
         "id": "service_id",
         "name": "Service Name",
         "description": "Service description",
         "categories": ["category1", "category2"],
         "address": "123 Health St",
         "phone_numbers": [{
            "number": "+1-123-456-7890",
            "type": "Main"
         }],
         "website": "https://example.com",
         "hours": "Monday-Friday 9AM-5PM"
      }
   ],
   "no_services_found": false
}

Response JSON Object:

• message (string) – Generated recommendation text

• is_emergency (boolean) – Indicates if the query suggests an emergency

• is_out_of_scope (boolean) – Indicates if the query is outside service scope

• services (array) – List of relevant health services (optional)

• no_services_found (boolean) – Indicates if no matching services were found

Status Codes:

• 200 OK – Recommendation generated successfully

• 422 Unprocessable Entity – Invalid request parameters

• 500 Internal Server Error – Server error

Question Generation

GET /questions

Generate follow-up questions based on the initial query and recommendation.

Example Request

GET /questions?query=mental+health+support&recommendation=Based+on+your+query...

Query Parameters:

• query (string) – The user’s original health query (required)

• recommendation (string) – The previously generated recommendation (required)

Response Body

{
   "questions": [
      "Do you prefer in-person or virtual care?",
      "What type of mental health support are you looking for?"
   ]
}

Response JSON Object:

• questions (array) – List of generated follow-up questions

Status Codes:

• 200 OK – Questions generated successfully

• 400 Bad Request – Invalid query parameters

• 500 Internal Server Error – Server error

Recommendation Refinement

POST /refine_recommendations

Refine the initial recommendation based on answers to follow-up questions.

Request Body

{
   "query": {
      "query": "mental health support",
      "latitude": 43.6532,
      "longitude": -79.3832,
      "radius": 5000
   },
   "questions": ["Do you prefer in-person or virtual care?"],
   "answers": ["in-person"],
   "recommendation": "Previous recommendation text..."
}

Request JSON Object:

• query (object) – Query object containing:

• query.query (string) – The user’s health-related query (required)

• query.latitude (number) – Optional latitude for location-based search

• query.longitude (number) – Optional longitude for location-based search

• query.radius (number) – Optional search radius in meters

• questions (array) – List of follow-up questions (required)

• answers (array) – User’s answers to the follow-up questions (required)

• recommendation (string) – The previous recommendation (required)

Response Body

{
   "message": "Based on your preferences...",
   "is_emergency": false,
   "is_out_of_scope": false,
   "services": [
      {
         "id": "service_id",
         "name": "Service Name",
         "description": "Service description"
      }
   ],
   "no_services_found": false
}

Response JSON Object:

• message (string) – Refined recommendation text

• is_emergency (boolean) – Updated emergency status

• is_out_of_scope (boolean) – Updated scope status

• services (array) – Updated list of relevant services (optional)

• no_services_found (boolean) – Indicates if no matching services were found

Status Codes:

• 200 OK – Recommendation refined successfully

• 422 Unprocessable Entity – Invalid request data

• 500 Internal Server Error – Server error

Service Information

GET /services/all

Retrieve all available health services from the database.

Response Body

[
   {
      "id": "service_id",
      "name": "Service Name",
      "description": "Service description",
      "categories": ["category1", "category2"],
      "address": "123 Health St",
      "phone_numbers": [{
         "number": "+1-123-456-7890",
         "type": "Main"
      }],
      "website": "https://example.com",
      "hours": "Monday-Friday 9AM-5PM"
   }
]

Response JSON Object:

• services (array) – List of all health services

Status Codes:

• 200 OK – Services retrieved successfully

• 500 Internal Server Error – Server error

GET /services/count

Get the total number of available health services.

Response Body

{
   "count": 150
}

Response JSON Object:

• count (integer) – Total number of services in the database

Status Codes:

• 200 OK – Count retrieved successfully

• 500 Internal Server Error – Server error

Error Responses

All endpoints may return the following error responses:

{
   "detail": "Error message describing what went wrong"
}

Common HTTP Status Codes

• 200 OK: Request successful

• 400 Bad Request: Invalid parameters

• 422 Unprocessable Entity: Invalid request body

• 500 Internal Server Error: Server-side error