Knowledge | Navigation SDK | Android Docs

MapGPT taps into Mapbox' proprietary map data layers, which encompasses essential geographic information such as road networks, points of interest, addresses, and real-time traffic data. These data layers serve as the foundation for MapGPT's location-aware interactions, ensuring accurate and contextually relevant responses.

Suppose a user asks, "Where's the nearest station?", "How's the traffic ahead?", or "What can you tell me about this city?". In such cases, the AI assistant adeptly determines if the user is seeking a charging or fuel station, offers current traffic updates, or unveils hidden facets of a city you thought you knew inside out. As well as provide interesting facts or stories as a source of conversation, entertainment, and utility.

What is sent to MapGPT?

The data sent to MapGPT can be categorized into five main contexts: App, User, Vehicle, Route, and EV. Each of these contexts contains specific details that aid MapGPT in understanding and efficiently processing requests. This data is notably adaptable, allowing customization and expansion based on customer requirements. Contact sales for information.

Full context overview

Required

Property	Type	Description
`userContext`	`object`	Information about the user's current location, point of interest, and prevailing weather conditions.

Optional

If not provided, the value will be assigned as null.

Property	Type	Description
`appContext`	`object`	Details about the application, such as localization preferences, battery status, and more.
`vehicleContext`	`object`	Specifics about the user's vehicle including type, battery status, and current conditions within the vehicle.
`routeContext`	`object`	Data about the active navigation route, such as ETA, distance remaining, and potential alternate routes.
`evContext`	`object`	Details about electric vehicles, primarily focused on nearby charging stations.


val context = MapGptContextDTO(
    userContext = MapGptUserContextDTO(...),
    appContext = MapGptAppContextDTO(...),
    vehicleContext = MapGptVehicleContextDTO(...),
    routeContext = MapGptRouteContextDTO(...),
    evContext = MapGptEVContextDTO(...),
)

User context

Required

Property	Type	Description
`lat`	`string`	Latitude used for reverse geocoding, and searching nearby places.
`lon`	`string`	Longitude used for reverse geocoding, and searching nearby places.
`heading`	`string`	Heading of the user's current direction. The property is optional.
`placeName`	`string`	Recognizable name or title of the user's location or destination.


val userContext = MapGptUserContextDTO(
    lat = "37.7694777",
    lon = "-122.486135",
    heading = "332.434195",
    placeName = "Golden Gate Park, San Francisco, CA",
)

App context

Optional

If not provided, the value will be assigned as null.

Property	Type	Description
`locale`	`string`	The language and regional settings of the application.
`temperatureUnits`	`string`	Measurement units (e.g., Celsius or Fahrenheit) used for temperature display.
`distanceUnits`	`string`	Measurement units (e.g., Kilometers or Miles) used for distance display.
`clientTime`	`string`	Current time from the application's perspective.
`media`	`object`	Active media context, like now playing song or media state.


val locale = Locale.getDefault()
val media = MapGptMusicContextDTO(
    name = "Shake It Off",
    artist = "Taylor Swift",
    state = "Playing"
)
val appContext = MapGptAppContextDTO(
    locale = locale.toLanguageTag(),
    temperatureUnits = "Fahrenheit", // or "Celsius",
    distanceUnits = "mi", // or "km",
    clientTime = SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss", Locale.getDefault())
        .format(Calendar.getInstance().time),
    media = media,
)

Vehicle Context

Optional

If not provided, the value will be assigned as null.

Property	Type	Description
`fuel`	`string`	Type of fuel or energy source the vehicle uses. Examples are gasoline, diesel, biodiesel, electric, hydrogen, and hybrid.
`batteryLevel`	`integer`	For electric and hybrid vehicles, the percentage of battery remaining.
`acTemperature`	`integer`	The set temperature of the vehicle.
`acStatus`	`string`	Active status of the air conditioning system (e.g., on, off).


val vehicleContext = MapGptVehicleContextDTO(
    fuel = "Gas",
    batteryLevel = 25,
    acTemperature = 70f,
    acStatus = "on",
)

Route Context

Optional

If not provided, the value will be assigned as null.

Property	Type	Description
`active`	`boolean`	Indicates when the navigation experience is following turn-by-turn guidance.
`eta`	`string`	Predicted time of arrival to the current waypoint.
`timeLeft`	`integer`	Duration remaining to reach the route destination in minutes.
`distanceLeft`	`double`	Distance remaining to reach the route destination. The unit will be either in mi or km depending on `appContext.distanceUnits`
`maxCongestion`	`integer`	The level of congestion in numeric form, from 0-100. A value of 0 indicates no congestion, a value of 100 indicates maximum congestion.
`typicalDuration`	`integer`	Usual travel time for the current route under normal conditions in minutes.
`alternateRoutes`	`integer`	Available alternative routes to the current destination.
`speed`	`double`	Current speed of the vehicle in meters per second.
`speedLimit`	`double`	Maximum permissible speed for the current road segment in meters per second.
`origin`	`object`	Start point of the current route.
`destination`	`object`	End point of the current route.


val origin = MapGptLocationDTO(
    lat = "37.7694777",
    lon = "-122.486135",
    placeName = "Golden Gate Park, San Francisco, CA",
)
val destination = MapGptLocationDTO(
    lat = "37.8255",
    lon = "-122.4994",
    placeName = "Hawk Hill, San Francisco, CA",
)
val routeContext = MapGptRouteContextDTO(
    active = true,
    eta = "2024-09-09T16:16:00",
    timeLeft = 19,
    distanceLeft = 9.050983807299744,
    maxCongestion = 38,
    typicalDuration = 18,
    alternateRoutes = 2,
    speed = 8.673388481140137,
    speedLimit = 11.176,
    origin = origin,
    destination = destination,
)

EV Context

Optional

If not provided, the value will be assigned as null.

Property	Type	Description
`nearbyStations`	`list`	A list of nearby charging stations and their information, useful for electric vehicles.


val evStation1 = MapGptEVStationDTO(
    name = "EV Station 1",
    distance = "5 mi", // 8 km depending on distanceUnits from appContext
)
val evStation2 = MapGptEVStationDTO(
    name = "EV Station 2",
    distance = "6 mi", // 9.6 km depending on distanceUnits from appContext
)
val evContext = MapGptEVContextDTO(
    nearbyStations = listOf(evStation1, evStation2)
)

When is it sent to MapGPT?

The context is a part of MapGptService.postPromptsForStreaming API call. Whenever a user issues a prompt, all the context mentioned above can be transmitted via the API. Out of all context only userContext is required and all others are optional. It is recommended to send the context if data is available, as sharing all with the AI system can significantly enhance the relevance and quality of interactions.


val context = MapGptContextDTO(
    userContext = MapGptUserContextDTO(
        lat = "37.7694777",
        lon = "-122.486135",
        placeName = "Golden Gate Park, San Francisco, CA",
    ),
    appContext = MapGptAppContextDTO(
        locale = "en",
        temperatureUnits = "Celsius", // or "Fahrenheit",
        distanceUnits = "km", // or "mi",
        clientTime = SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss", Locale.getDefault())
            .format(Calendar.getInstance().time),
    ),
)
val request = MapGptStreamingRequest(
    prompt = prompt,
    context = context,
)
mapGptService.postPromptsForStreaming(request)

MapGPT context with Dash

When using Dash application instead of MapGPT SDK, you don't need to construct the context as shown above. Dash application already constructs the context and sends it via the postPromptsForStreaming API call.

How to update the context with UX Framework?

When using MapGPT with UX Framework, the context is created with default values. There might be use cases where you would need to update the context with new data values. MapGPT provides a context override API that allows you to update the context at runtime. For example, if you want to update MapGPT about the car battery level being low at 10%, you can do the following:


Dash.controller.updateMapGptContextOverrides {
    vehicleContext.value = { contextDTO ->
        contextDTO.copy(
            batteryLevel = 10
        )
    }
    // Similarly, other contexts can be overridden
    evContext.value = { contextDTO -> contextDTO.copy(...) }
    appContext.value = { contextDTO -> contextDTO.copy(...) }
    userContext.value = { contextDTO -> contextDTO.copy(...) }
    routeContext.value = { contextDTO -> contextDTO.copy(...) }
}

Additional Developer Resources

Mapbox Developer Discord

Developer Cheatsheet

Mapbox Support

Ask AI

Was this page helpful?

What is sent to MapGPT?​

Full context overview​

Required​

Optional​

User context​

Required​

App context​

Optional​

Vehicle Context​

Optional​

Route Context​

Optional​

EV Context​

Optional​

When is it sent to MapGPT?​

How to update the context with UX Framework?​

What is sent to MapGPT?

Full context overview

Required

Optional

User context

Required

App context

Optional

Vehicle Context

Optional

Route Context

Optional

EV Context

Optional

When is it sent to MapGPT?

How to update the context with UX Framework?