AI & Geocoding API Reference

WayFy’s AI API bridges natural language and map interactions. The mapgpt endpoint accepts plain-language prompts from the map search bar — such as “find wheelchair-friendly cafés near the Prado” — and returns structured data that the WayFy frontend uses to pan the map, apply category filters, and set accessibility filters in a single step. Geocoding endpoints resolve text queries into geographic coordinates using Photon and Nominatim.

The mapgpt endpoint is powered by llama-3.3-70b-versatile via the Groq API and requires a valid GROQ_API_KEY environment variable set on the server. Geocoding endpoints call external public services — no API key is required for those.

All AI endpoints are rate-limited. Exceeding the limit returns 429 Too Many Requests. Rate limits are: mapgpt — 20 requests/minute; geocoding endpoints — 30 requests/minute each.

Map Assistant

POST /api/ai/mapgpt

Interprets a free-text user prompt and returns structured map directives. The LLM extracts intent from the prompt and responds with a JSON object that WayFy’s frontend consumes to update the map state — panning to a location, filtering by category, and applying accessibility constraints simultaneously. Authentication: None
Rate Limit: 20 requests per minute

This endpoint is designed to be called from the WayFy map search bar on every submission. The response message field contains a natural-language reply suitable for display to the user, while the other fields drive programmatic map updates.

Request

prompt

string

required

The user’s natural-language search query (e.g. "restaurants with accessible parking near Retiro Park, Madrid"). Returns 400 Bad Request with {"msg": "Prompt vacío"} if the prompt is missing or blank.

Response

The LLM returns a JSON object with the following fields. The exact shape depends on the model’s output.

poi

string

A specific point of interest name extracted from the prompt, if any (e.g. "Retiro Park"). null if no specific POI was detected.

address

string

A street address or neighbourhood extracted from the prompt. null if not detected.

place

string

A city, region, or general place name extracted from the prompt (e.g. "Madrid"). null if not detected.

Error responses

msg

string

"Prompt vacío" — returned with 400 when the prompt is empty or whitespace-only.

Example

curl -X POST http://localhost:3001/api/ai/mapgpt \
  -H "Content-Type: application/json" \
  -d '{"prompt": "wheelchair-friendly restaurants near Retiro Park Madrid"}'

{
  "poi": "Retiro Park",
  "address": null,
  "place": "Madrid",
  "categories": ["gastronomia"],
  "filters": ["yes"],
  "message": "Showing fully wheelchair-accessible restaurants near Retiro Park, Madrid."
}

Empty prompt error:

{
  "msg": "Prompt vacío"
}

Cafés with limited access
Multi-category search
No accessibility filter

Prompt: "coffee shops that have some accessibility near the Gothic Quarter Barcelona"

{
  "poi": "Gothic Quarter",
  "address": null,
  "place": "Barcelona",
  "categories": ["gastronomia"],
  "filters": ["limited"],
  "message": "Showing coffee shops with limited wheelchair accessibility near the Gothic Quarter, Barcelona."
}

Prompt: "accessible hotels and transport in Seville"

{
  "poi": null,
  "address": null,
  "place": "Seville",
  "categories": ["alojamiento", "transporte"],
  "filters": ["yes"],
  "message": "Showing accessible hotels and transport options in Seville."
}

Prompt: "museums in Rome"

{
  "poi": null,
  "address": null,
  "place": "Rome",
  "categories": ["cultura_turismo"],
  "filters": [],
  "message": "Showing museums in Rome."
}

Geocoding

GET /api/ai/geocode?q=<query>

Resolves a text query to geographic coordinates using Nominatim. Returns the best matching feature — including its center point and geometry — or null if no match is found. Returns 400 if the query is empty. Authentication: None
Rate Limit: 30 requests per minute

Request

string

required

The search query to geocode (e.g. "Prado Museum, Madrid"). Returns 400 if blank.

Response

feature

object

The best-matching geocoded feature, or null if no result was found.

Show Feature object

string

The original query string used as the identifier.

center

array

[longitude, latitude] coordinate pair for the result’s center point.

geometry

object

GeoJSON Point geometry object.

places_name

string

The original query string (Nominatim display name is not forwarded).

text

string

The original query string.

Example

curl "http://localhost:3001/api/ai/geocode?q=Prado+Museum+Madrid"

{
  "feature": {
    "id": "Prado Museum Madrid",
    "center": [-3.69219, 40.41382],
    "geometry": {
      "type": "Point",
      "coordinates": [-3.69219, 40.41382]
    },
    "places_name": "Prado Museum Madrid",
    "text": "Prado Museum Madrid"
  }
}

No match found:

{
  "feature": null
}

GET /api/ai/geocode-poi?q=<query>

Resolves a POI query to geographic coordinates with automatic dual-source fallback. The endpoint first queries Photon (optimised for POI search) and falls back to Nominatim if Photon returns no results. For long queries, progressively shorter sub-strings are tried through both services before giving up. Returns {"feature": null} (never an error) if no result is found even after all attempts. Authentication: None
Rate Limit: 30 requests per minute

Use geocode-poi for named place lookups (e.g. a specific restaurant or landmark). Use geocode for address or area lookups (e.g. resolving a street address or city name). Both endpoints return the same feature shape.

Request

string

required

The POI name or query to geocode (e.g. "Sagrada Família"). An empty query returns {"feature": null} with 200 rather than an error.

Response

feature

object

The best-matching geocoded feature, or null if neither Photon nor Nominatim returned a result. Same shape as the geocode endpoint.

Show Feature object

string

The original query string.

center

array

[longitude, latitude] coordinate pair for the result’s center point.

geometry

object

GeoJSON Point geometry object.

places_name

string

The original query string.

text

string

The original query string.

Example

curl "http://localhost:3001/api/ai/geocode-poi?q=Sagrada+Fam%C3%ADlia"

{
  "feature": {
    "id": "Sagrada Família",
    "center": [2.17490, 41.40363],
    "geometry": {
      "type": "Point",
      "coordinates": [2.17490, 41.40363]
    },
    "places_name": "Sagrada Família",
    "text": "Sagrada Família"
  }
}

No result found:

{
  "feature": null
}

Overview

Endpoints

AI & Geocoding API Reference

Map Assistant

POST /api/ai/mapgpt

Request

Response

Error responses

Example

Geocoding

GET /api/ai/geocode?q=<query>

Request

Response

Example

GET /api/ai/geocode-poi?q=<query>

Request

Response

Example

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Map Assistant

​POST /api/ai/mapgpt

​Request

​Response

​Error responses

​Example

​Geocoding

​GET /api/ai/geocode?q=<query>

​Request

​Response

​Example

​GET /api/ai/geocode-poi?q=<query>

​Request

​Response

​Example

Build docs developers (and LLMs) love

Map Assistant

POST /api/ai/mapgpt

Request

Response

Error responses

Example

Geocoding

GET /api/ai/geocode?q=<query>

Request

Response

Example

GET /api/ai/geocode-poi?q=<query>

Request

Response

Example