port

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

Overview

The port module allows you to:

Search ports with pagination
Filter ports by multiple criteria (name, location, status, etc.)
Sort port results by various properties
Retrieve specific port fields to optimize API calls
Work with port location data (coordinates, radius)

Main Components

GetAndSearchPortsByPage

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

Models

Port

Represents a port entity with complete information.

Properties:

id: Int - Unique port identifier
name: String - Port name
description: String - Port description
identification: String - Port identification code
country: String - Country where port is located
department: String - Department/state where port is located
city: String - City where port is located
address: String - Port address
latitude: Double - Port latitude coordinate
longitude: Double - Port longitude coordinate
dockIds: List<Int> - List of dock IDs associated with this port
entranceRadiusMeters: Int - Entrance radius in meters (to determine if inside port)
departureRadiusMeters: Int - Departure radius in meters (to determine if outside port)
status: PlaceStatusType - Port status (ACTIVE, INACTIVE, UNKNOWN)
companyId: Int - Company ID
addedOnDate: String - Creation date
updateOnDate: String - Last update date

PortFilters

Comprehensive filters for port search.

Properties: 17 different filter options including IDs, names, locations, coordinates, and more.

PortOrderSort

Sorting configuration with 17 sortable properties.

Types

PortProperty

Enum with 17 properties for field selection.

Values:

ID, NAME, DESCRIPTION, IDENTIFICATION
COUNTRY, DEPARTMENT, CITY, ADDRESS
LATITUDE, LONGITUDE, DOCK_IDS
ENTRANCE_RADIUS_IN_MTS, DEPARTURE_RADIUS_IN_MTS
STATUS, COMPANY_ID, ADDED_ON_DATE, UPDATE_ON_DATE

Usage Examples

Basic Search - Get All Ports

import com.servinformacion.smart1sdk.android.port.GetAndSearchPortsByPage
import com.servinformacion.smart1sdk.android.core.ResultS1SDK

class PortViewModel : ViewModel() {
    
    private val getPorts = GetAndSearchPortsByPage()
    
    fun loadPorts() {
        viewModelScope.launch {
            val result = getPorts(
                page = 1,
                pageQuantity = 20
            )
            
            when (result) {
                is ResultS1SDK.Success -> {
                    val ports = result.data.data
                    val totalPages = result.data.paginationInfo.totalPages
                    // Handle success
                }
                is ResultS1SDK.Error -> {
                    // Handle error
                }
            }
        }
    }
}

Filter by Port Name

import com.servinformacion.smart1sdk.android.port.model.PortFilters
import com.servinformacion.smart1sdk.android.core.types.ApiSearchType

suspend fun searchPortsByName(portName: String) {
    val getPorts = GetAndSearchPortsByPage()
    
    val result = getPorts(
        filters = PortFilters(
            names = listOf(portName)
        ),
        searchType = ApiSearchType.CONTAINS,
        page = 1
    )
    
    // Handle result
}

Filter by Location (City and Country)

suspend fun getPortsByLocation(city: String, country: String) {
    val getPorts = GetAndSearchPortsByPage()
    
    val result = getPorts(
        filters = PortFilters(
            cities = listOf(city),
            countries = listOf(country)
        ),
        logicalOperator = ApiLogicalOperator.AND,
        page = 1
    )
    
    // Handle result
}

Filter by Status

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

suspend fun getActivePorts() {
    val getPorts = GetAndSearchPortsByPage()
    
    val result = getPorts(
        filters = PortFilters(
            status = listOf(PlaceStatusType.ACTIVE)
        ),
        page = 1
    )
    
    when (result) {
        is ResultS1SDK.Success -> {
            val activePorts = result.data.data
            println("Found ${activePorts.size} active ports")
        }
        is ResultS1SDK.Error -> {
            println("Error: ${result.error}")
        }
    }
}

Sort Ports by Name

import com.servinformacion.smart1sdk.android.port.model.PortOrderSort
import com.servinformacion.smart1sdk.android.core.types.ApiSortType

suspend fun getPortsSortedByName() {
    val getPorts = GetAndSearchPortsByPage()
    
    val result = getPorts(
        orderSort = PortOrderSort(
            name = ApiSortType.ASC
        ),
        page = 1
    )
    
    // Handle result
}

Optimized Field Selection

import com.servinformacion.smart1sdk.android.port.types.PortProperty

suspend fun getPortBasicInfo() {
    val getPorts = GetAndSearchPortsByPage()
    
    val result = getPorts(
        fields = listOf(
            PortProperty.ID,
            PortProperty.NAME,
            PortProperty.CITY,
            PortProperty.COUNTRY,
            PortProperty.STATUS
        ),
        page = 1,
        pageQuantity = 50
    )
    
    // Handle result
}

Search Ports Near Coordinates

suspend fun getPortsNearLocation(lat: Double, lon: Double) {
    val getPorts = GetAndSearchPortsByPage()
    
    val result = getPorts(
        filters = PortFilters(
            latitudes = listOf(lat),
            longitudes = listOf(lon)
        ),
        searchType = ApiSearchType.CONTAINS,
        page = 1
    )
    
    // Handle result
}

Advanced Search with Multiple Filters

suspend fun advancedPortSearch() {
    val getPorts = GetAndSearchPortsByPage()
    
    val result = getPorts(
        filters = PortFilters(
            countries = listOf("Colombia", "Mexico"),
            status = listOf(PlaceStatusType.ACTIVE),
            companyIds = listOf(1)
        ),
        logicalOperator = ApiLogicalOperator.AND,
        orderSort = PortOrderSort(
            name = ApiSortType.ASC,
            city = ApiSortType.ASC
        ),
        searchType = ApiSearchType.EXACT,
        page = 1,
        pageQuantity = 20
    )
    
    when (result) {
        is ResultS1SDK.Success -> {
            val dataSet = result.data
            println("Total ports: ${dataSet.paginationInfo.totalRecords}")
            
            dataSet.data.forEach { port ->
                println("${port.name} - ${port.city}, ${port.country}")
            }
        }
        is ResultS1SDK.Error -> {
            println("Error: ${result.error}")
        }
    }
}

Get Ports with Dock Information

suspend fun getPortsWithDocks() {
    val getPorts = GetAndSearchPortsByPage()
    
    val result = getPorts(
        fields = listOf(
            PortProperty.ID,
            PortProperty.NAME,
            PortProperty.DOCK_IDS,
            PortProperty.ADDRESS
        ),
        page = 1
    )
    
    when (result) {
        is ResultS1SDK.Success -> {
            result.data.data.forEach { port ->
                println("Port: ${port.name}")
                println("Docks: ${port.dockIds.size}")
                port.dockIds.forEach { dockId ->
                    println("  - Dock ID: $dockId")
                }
            }
        }
        is ResultS1SDK.Error -> {
            // Handle error
        }
    }
}

Check Port Radius Configuration

suspend fun analyzePortRadius(portId: Int) {
    val getPorts = GetAndSearchPortsByPage()
    
    val result = getPorts(
        filters = PortFilters(ids = listOf(portId)),
        fields = listOf(
            PortProperty.ID,
            PortProperty.NAME,
            PortProperty.ENTRANCE_RADIUS_IN_MTS,
            PortProperty.DEPARTURE_RADIUS_IN_MTS,
            PortProperty.LATITUDE,
            PortProperty.LONGITUDE
        )
    )
    
    when (result) {
        is ResultS1SDK.Success -> {
            val port = result.data.data.firstOrNull()
            port?.let {
                println("Port: ${it.name}")
                println("Location: ${it.latitude}, ${it.longitude}")
                println("Entrance Radius: ${it.entranceRadiusMeters}m")
                println("Departure Radius: ${it.departureRadiusMeters}m")
            }
        }
        is ResultS1SDK.Error -> {
            // Handle error
        }
    }
}

Pagination Example

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

Important Notes

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

entranceRadiusMeters: Check if device is inside port area
departureRadiusMeters: Check if device has left port area

Coordinates: Latitude and longitude are in decimal degrees format.
Status Types:

ACTIVE: Port is operational
INACTIVE: Port is not operational
UNKNOWN: Status not determined

Search Types:

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

Response Structure

data class DataSet<T>(
    val data: List<T>,                   // List of ports
    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 ports 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 port data locally
Error Handling: Always handle potential errors
Radius Checks: Use entrance/departure radius for geofencing

Use Cases

Port Selection: Display list of available ports
Location Tracking: Determine when vehicle enters/exits port
Route Planning: Find ports along a route
Geofencing: Set up alerts based on port radius
Port Management: View and filter ports by various criteria

Packages

com.servinformacion.smart1sdk.android.port

androidJvm

com.servinformacion.smart1sdk.android.port.model

androidJvm

com.servinformacion.smart1sdk.android.port.types

androidJvm