route

This module provides functionality to search and retrieve routes from the Smart1 SDK API.

Overview

The route module allows you to:

Search routes with pagination
Filter routes by multiple criteria (name, type, status, distance, etc.)
Sort route results by various properties
Retrieve specific route fields to optimize API calls
Work with route information including segments and polylines

Main Components

GetAndSearchRoutesByPage

Main use case for retrieving routes from the API with advanced filtering and pagination.

Models

Route

Represents a route entity with complete information.

Properties:

id: Int - Unique route identifier
name: String - Route name
description: String - Route description
identification: String - Route identification code
status: PlaceStatusType - Route status (ACTIVE, INACTIVE, UNKNOWN)
type: RouteType - Route type (ONE_WAY_TRIP, ROUND_TRIP, MULTI_STOP_TRIP)
distanceUnit: DistanceUnit - Distance unit (METER, KILOMETER, FOOT, YARD, MILE)
totalDuration: String - Total route duration
totalDistance: Int - Total route distance
routeInfo: List<RouteInfo> - Route segment information
tripTypeIds: List<Int> - Trip type IDs
companyId: Int - Company ID
addedOnDate: String - Creation date
updateOnDate: String - Last update date

RouteInfo

Represents a route segment between two ports.

Properties:

originPortId: Int - Origin port ID
destinationPortId: Int - Destination port ID
duration: String - Segment duration
sequence: Int - Segment sequence order
distance: Int - Segment distance
segmentPolyline: String - Encoded polyline for the segment

RouteFilters

Comprehensive filters for route search.

Properties: 13 different filter options including IDs, names, types, distances, and more.

RouteOrderSort

Sorting configuration with 14 sortable properties.

Types

RouteProperty

Enum with 14 properties for field selection.

Values:

ID, NAME, IDENTIFICATION, STATUS, DESCRIPTION
TYPE, DISTANCE_UNIT, TOTAL_DURATION, TOTAL_DISTANCE
ROUTE_INFO, TRIP_TYPE_IDS, COMPANY_ID
ADDED_ON_DATE, UPDATE_ON_DATE

RouteType

Enum representing route types.

Values:

ONE_WAY_TRIP - Single direction route
ROUND_TRIP - Return to origin route
MULTI_STOP_TRIP - Multiple stops route
UNKNOWN - Unknown type

DistanceUnit

Enum for distance measurement units.

Values:

METER - Meters (m)
KILOMETER - Kilometers (km)
FOOT - Feet (ft)
YARD - Yards (yd)
MILE - Miles (mi)
UNKNOWN - Unknown unit

StateName

Enum for route state names.

Values:

ACTIVE - Route is active
INACTIVE - Route is inactive
DELETED - Route is deleted
UNKNOWN - Unknown state

Usage Examples

Basic Search - Get All Routes

import com.servinformacion.smart1sdk.android.route.GetAndSearchRoutesByPage
import com.servinformacion.smart1sdk.android.core.ResultS1SDK

class RouteViewModel : ViewModel() {
    
    private val getRoutes = GetAndSearchRoutesByPage()
    
    fun loadRoutes() {
        viewModelScope.launch {
            val result = getRoutes(
                page = 1,
                pageQuantity = 20
            )
            
            when (result) {
                is ResultS1SDK.Success -> {
                    val routes = result.data.data
                    val totalPages = result.data.paginationInfo.totalPages
                    // Handle success
                }
                is ResultS1SDK.Error -> {
                    // Handle error
                }
            }
        }
    }
}

Filter by Route Type

import com.servinformacion.smart1sdk.android.route.model.RouteFilters
import com.servinformacion.smart1sdk.android.route.types.RouteType

suspend fun getRoundTripRoutes() {
    val getRoutes = GetAndSearchRoutesByPage()
    
    val result = getRoutes(
        filters = RouteFilters(
            types = listOf(RouteType.ROUND_TRIP)
        ),
        page = 1
    )
    
    // Handle result
}

Filter by Route Name

import com.servinformacion.smart1sdk.android.core.types.ApiSearchType

suspend fun searchRoutesByName(routeName: String) {
    val getRoutes = GetAndSearchRoutesByPage()
    
    val result = getRoutes(
        filters = RouteFilters(
            names = listOf(routeName)
        ),
        searchType = ApiSearchType.CONTAINS,
        page = 1
    )
    
    // Handle result
}

Filter by Status

import com.servinformacion.smart1sdk.android.core.types.PlaceStatusType

suspend fun getActiveRoutes() {
    val getRoutes = GetAndSearchRoutesByPage()
    
    val result = getRoutes(
        filters = RouteFilters(
            status = listOf(PlaceStatusType.ACTIVE)
        ),
        page = 1
    )
    
    when (result) {
        is ResultS1SDK.Success -> {
            val activeRoutes = result.data.data
            println("Found ${activeRoutes.size} active routes")
        }
        is ResultS1SDK.Error -> {
            println("Error: ${result.error}")
        }
    }
}

Sort Routes by Name

import com.servinformacion.smart1sdk.android.route.model.RouteOrderSort
import com.servinformacion.smart1sdk.android.core.types.ApiSortType

suspend fun getRoutesSortedByName() {
    val getRoutes = GetAndSearchRoutesByPage()
    
    val result = getRoutes(
        orderSort = RouteOrderSort(
            name = ApiSortType.ASC
        ),
        page = 1
    )
    
    // Handle result
}

Optimized Field Selection

import com.servinformacion.smart1sdk.android.route.types.RouteProperty

suspend fun getRouteBasicInfo() {
    val getRoutes = GetAndSearchRoutesByPage()
    
    val result = getRoutes(
        fields = listOf(
            RouteProperty.ID,
            RouteProperty.NAME,
            RouteProperty.TYPE,
            RouteProperty.TOTAL_DISTANCE,
            RouteProperty.TOTAL_DURATION
        ),
        page = 1,
        pageQuantity = 50
    )
    
    // Handle result
}

Filter by Distance

suspend fun getRoutesByDistance(minDistance: Int) {
    val getRoutes = GetAndSearchRoutesByPage()
    
    val result = getRoutes(
        filters = RouteFilters(
            totalDistances = listOf(minDistance)
        ),
        searchType = ApiSearchType.CONTAINS,
        page = 1
    )
    
    // Handle result
}

Advanced Search with Multiple Filters

import com.servinformacion.smart1sdk.android.route.types.DistanceUnit

suspend fun advancedRouteSearch() {
    val getRoutes = GetAndSearchRoutesByPage()
    
    val result = getRoutes(
        filters = RouteFilters(
            types = listOf(RouteType.ONE_WAY_TRIP, RouteType.ROUND_TRIP),
            status = listOf(PlaceStatusType.ACTIVE),
            distanceUnits = listOf(DistanceUnit.KILOMETER),
            companyIds = listOf(1)
        ),
        logicalOperator = ApiLogicalOperator.AND,
        orderSort = RouteOrderSort(
            totalDistance = ApiSortType.ASC,
            name = ApiSortType.ASC
        ),
        searchType = ApiSearchType.EXACT,
        page = 1,
        pageQuantity = 20
    )
    
    when (result) {
        is ResultS1SDK.Success -> {
            val dataSet = result.data
            println("Total routes: ${dataSet.paginationInfo.totalRecords}")
            
            dataSet.data.forEach { route ->
                println("${route.name} - ${route.totalDistance} ${route.distanceUnit.apiName}")
            }
        }
        is ResultS1SDK.Error -> {
            println("Error: ${result.error}")
        }
    }
}

Get Route with Segment Information

suspend fun getRouteWithSegments(routeId: Int) {
    val getRoutes = GetAndSearchRoutesByPage()
    
    val result = getRoutes(
        filters = RouteFilters(ids = listOf(routeId)),
        fields = listOf(
            RouteProperty.ID,
            RouteProperty.NAME,
            RouteProperty.ROUTE_INFO,
            RouteProperty.TOTAL_DISTANCE,
            RouteProperty.TOTAL_DURATION
        )
    )
    
    when (result) {
        is ResultS1SDK.Success -> {
            val route = result.data.data.firstOrNull()
            route?.let {
                println("Route: ${it.name}")
                println("Total Distance: ${it.totalDistance}")
                println("Total Duration: ${it.totalDuration}")
                println("Segments:")
                
                it.routeInfo.sortedBy { info -> info.sequence }.forEach { segment ->
                    println("  Segment ${segment.sequence}:")
                    println("    From Port: ${segment.originPortId}")
                    println("    To Port: ${segment.destinationPortId}")
                    println("    Distance: ${segment.distance}")
                    println("    Duration: ${segment.duration}")
                }
            }
        }
        is ResultS1SDK.Error -> {
            // Handle error
        }
    }
}

Display Route on Map

suspend fun getRoutePolylines(routeId: Int) {
    val getRoutes = GetAndSearchRoutesByPage()
    
    val result = getRoutes(
        filters = RouteFilters(ids = listOf(routeId)),
        fields = listOf(
            RouteProperty.ID,
            RouteProperty.NAME,
            RouteProperty.ROUTE_INFO
        )
    )
    
    when (result) {
        is ResultS1SDK.Success -> {
            val route = result.data.data.firstOrNull()
            route?.routeInfo?.forEach { segment ->
                // Decode and display polyline on map
                val polyline = segment.segmentPolyline
                drawPolylineOnMap(polyline)
            }
        }
        is ResultS1SDK.Error -> {
            // Handle error
        }
    }
}

Filter by Multiple Route Types

suspend fun getMultiStopAndRoundTripRoutes() {
    val getRoutes = GetAndSearchRoutesByPage()
    
    val result = getRoutes(
        filters = RouteFilters(
            types = listOf(
                RouteType.MULTI_STOP_TRIP,
                RouteType.ROUND_TRIP
            )
        ),
        logicalOperator = ApiLogicalOperator.OR,
        page = 1
    )
    
    // Handle result
}

Pagination Example

class RouteListViewModel : ViewModel() {
    private val getRoutes = GetAndSearchRoutesByPage()
    private var currentPage = 1
    private val pageSize = 20
    
    suspend fun loadNextPage() {
        val result = getRoutes(
            page = currentPage,
            pageQuantity = pageSize,
            orderSort = RouteOrderSort(name = ApiSortType.ASC)
        )
        
        when (result) {
            is ResultS1SDK.Success -> {
                val dataSet = result.data
                val routes = dataSet.data
                val hasMorePages = currentPage < dataSet.paginationInfo.totalPages
                
                // Update UI with routes
                updateRouteList(routes)
                
                if (hasMorePages) {
                    currentPage++
                }
            }
            is ResultS1SDK.Error -> {
                // Handle error
            }
        }
    }
}

Important Notes

Required Field: Always include RouteProperty.ID in the fields list.
Field Selection: Request only needed fields for better performance.
Pagination: Results are paginated. Use DataSet.paginationInfo to navigate.
Route Types:

ONE_WAY_TRIP: Single direction from A to B
ROUND_TRIP: From A to B and back to A
MULTI_STOP_TRIP: Multiple stops along the route

Distance Units: Routes can use different distance units. Check distanceUnit property.
Route Segments: routeInfo contains ordered segments. Use sequence to order them correctly.
Polylines: Segment polylines are encoded. Decode them to display on maps.
Search Types:

EXACT: Exact match
CONTAINS: Partial match (useful for text searches)

Response Structure

data class DataSet<T>(
    val data: List<T>,                   // List of routes
    val paginationInfo: PaginationInfo,  // Pagination metadata
    val capacityInfo: CapacityInfo       // API capacity information
)

Error Handling

Common errors:

CommonError.InvalidInputData - Invalid parameters (empty fields, invalid page)
ApiError.ExpiredToken - Session token expired (handled automatically)
ApiError.Unauthorized - Invalid or missing authentication
ApiError.NotFound - No routes found

Best Practices

Optimize Queries: Request only necessary fields
Use Filters: Narrow down results with appropriate filters
Pagination: Load data in pages for better performance
Caching: Consider caching route data locally
Error Handling: Always handle potential errors
Segment Order: Always sort routeInfo by sequence before processing

Use Cases

Route Selection: Display list of available routes
Route Planning: Find optimal routes by distance or duration
Map Display: Show route paths on maps using polylines
Route Analysis: Analyze route segments and distances
Trip Management: Manage different trip types (one-way, round-trip, multi-stop)

Packages

com.servinformacion.smart1sdk.android.route

androidJvm

com.servinformacion.smart1sdk.android.route.model

androidJvm

com.servinformacion.smart1sdk.android.route.types

androidJvm