Osmunda

https://github.com/sun-jiao/osmunda
Admin
Osmunda is an Android library that reads OpenStreetMap data in various formats (osm.pbf, osm.bz2,...
Tokens:10,513
Snippets:87
Trust Score:8
License:Apache-2.0
Update:6 months ago
Show doc for...
Tokens:
Raw
### Instantiate OsmosisReader

Source: https://github.com/sun-jiao/osmunda/blob/master/README.md

Create an instance of OsmosisReader to begin reading OSM data. No specific setup is required before instantiation.

```kotlin
val reader: Reader = OsmosisReader()
```

--------------------------------

### Complete OSM Data Import and Geocoding Example

Source: https://context7.com/sun-jiao/osmunda/llms.txt

This Kotlin code demonstrates the complete integration of Osmunda in an Android application. It covers importing OSM data using OsmosisReader, monitoring import progress, and then utilizing the imported data for both forward geocoding (searching by name) and reverse geocoding (finding places near coordinates). Ensure the OSM data file exists in the app's files directory.

```kotlin
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import kotlinx.coroutines.*
import moe.sunjiao.osmunda.Osmunda
import moe.sunjiao.osmunda.reader.OsmosisReader
import moe.sunjiao.osmunda.model.ImportOption
import moe.sunjiao.osmunda.geocoder.Geocoder
import moe.sunjiao.osmunda.geocoder.ReverseGeocoder
import java.io.File

class MapActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Run import on background thread
        CoroutineScope(Dispatchers.IO).launch {
            // Step 1: Import OSM data (one-time operation)
            val reader = OsmosisReader()
            reader.options.add(ImportOption.INCLUDE_WAYS)
            reader.commitFrequency = 10000

            val osmFile = File(filesDir.absolutePath + "/hubei-latest.osm.pbf")
            if (osmFile.exists()) {
                reader.readData(osmFile, this@MapActivity, "hubei")

                // Monitor progress
                while (reader.progress < 1.0 && reader.progress >= 0) {
                    val percent = (reader.progress * 100).toInt()
                    withContext(Dispatchers.Main) {
                        // Update UI with progress
                        println("Import progress: $percent%")
                    }
                    delay(1000)
                }
            }

            // Step 2: Use imported database for geocoding
            val osmunda = Osmunda(this@MapActivity)
            val database = osmunda.getDatabaseByName("hubei")

            // Forward geocoding: find location by name
            val geocoder = Geocoder(database)
            val searchResults = geocoder.search("Wuhan University", 5, 0)

            searchResults.forEach { result ->
                println("Found: ${result.name} at ${result.lat}, ${result.lon}")

                // Get detailed address (do this on-demand, not in bulk)
                val address = result.toAddress()
                println("Address: ${address.fullAddress}")
            }

            // Reverse geocoding: find places near coordinates
            val reverseGeocoder = ReverseGeocoder(database)
            val nearbyPlaces = reverseGeocoder.search(30.5, 114.3, 10, 0)

            nearbyPlaces.forEach { place ->
                println("Nearby: ${place.name}")
            }
        }
    }
}
```

--------------------------------

### Get List of Imported Databases

Source: https://github.com/sun-jiao/osmunda/blob/master/README.md

Retrieve a list of all databases that have been imported using Osmunda. You can also get a specific database by its name.

```kotlin
Osmunda(requireContext()).GetDatabaseList()
Osmunda(requireContext()).GetDatabaseByName(databaseName)
```

--------------------------------

### Manage Imported OSM Databases with Osmunda

Source: https://context7.com/sun-jiao/osmunda/llms.txt

Use the Osmunda class to get the database directory, list all available imported OSM databases, and open a specific database by name for geocoding operations.

```kotlin
import moe.sunjiao.osmunda.Osmunda
import android.database.sqlite.SQLiteDatabase
import java.io.File

val osmunda = Osmunda(context)

// Get the directory where OSM databases are stored
val databaseDir: File = osmunda.getDatabaseDir()

// List all imported OSM databases
val databases: Array<File>? = osmunda.getDatabaseList()
databases?.forEach { file ->
    println("Available database: ${file.name}")
}

// Open a specific database by name (without .sqlite extension)
val hubeiDatabase: SQLiteDatabase = osmunda.getDatabaseByName("hubei")
```

--------------------------------

### Get Import Status

Source: https://github.com/sun-jiao/osmunda/blob/master/README.md

Retrieve the number of OSM records read and inserted, as well as the current estimated progress percentage. The difference between read and inserted records is explained in the commitFrequency section.

```kotlin
reader.read
reader.insert
reader.progress
```

--------------------------------

### SearchResult.toAddress - Get Full Address Details

Source: https://context7.com/sun-jiao/osmunda/llms.txt

Converts a SearchResult object into a detailed Address object, providing access to various address components like country, state, city, street, and more. This method is CPU-intensive and should be used judiciously.

```APIDOC
## SearchResult.toAddress - Get Full Address Details

### Description
The `SearchResult` class can be converted to an `Address` object that provides detailed address components including country, state, city, county, town, street, house number, and more. This parsing respects locale-specific address formats.

### Method
This is a method of the `SearchResult` class.

### Endpoint
N/A (This is a client-side library method)

### Parameters
None

### Request Example
```kotlin
val database = Osmunda(context).getDatabaseByName("hubei")
val results = ReverseGeocoder(database).search(30.51910, 114.35775, 10, 0)

for (result in results) {
    val address: Address = result.toAddress()
    // ... access address components ...
}
```

### Response
#### Success Response
- **Address** (Address) - An Address object containing detailed address components.

#### Response Example
```json
{
  "fullAddress": "123 Main St, Anytown, CA 90210, USA",
  "name": "Example Business",
  "country": "USA",
  "state": "CA",
  "city": "Anytown",
  "county": "Example County",
  "town": "Example Town",
  "street": "Main St",
  "housenumber": "123",
  "housename": "Example House",
  "neighbourhood": "Example Neighbourhood",
  "postcode": "90210",
  "phone": "+1-555-123-4567",
  "website": "http://example.com",
  "latitude": 34.0522,
  "longitude": -118.2437
}
```

### Notes
Getting full address is CPU-intensive (0.3-3 seconds per result). Retrieve addresses on-demand rather than for entire result lists.
```

--------------------------------

### Import OSM Data from File using OsmosisReader

Source: https://context7.com/sun-jiao/osmunda/llms.txt

Initialize OsmosisReader, configure import options (relations, ways), set commit frequency, and read OSM data from a file into an SQLite database. Monitor progress via reader properties.

```kotlin
import moe.sunjiao.osmunda.reader.OsmosisReader
import moe.sunjiao.osmunda.reader.Reader
import moe.sunjiao.osmunda.model.ImportOption
import java.io.File

// Initialize the OSM reader
val reader: Reader = OsmosisReader()

// Optional: Include relations and ways data (increases storage but enables more features)
reader.options.add(ImportOption.INCLUDE_RELATIONS)
reader.options.add(ImportOption.INCLUDE_WAYS)

// Optional: Configure commit frequency for batch inserts (default: 5000)
// Lower values use less memory, higher values are faster
(reader as OsmosisReader).commitFrequency = 5000

// Read OSM data from a file and import to SQLite database
val osmFile = File(context.filesDir.absolutePath + "/hubei-latest.osm.pbf")
reader.readData(osmFile, context, "hubei")  // Creates "hubei.sqlite" database

// Monitor import progress (0.0 to 1.0)
val progress: Double = reader.progress
val recordsRead: Long = reader.read
val recordsInserted: Long = reader.insert
val totalElements: Long = reader.elementCount
```

--------------------------------

### Read Data from File

Source: https://github.com/sun-jiao/osmunda/blob/master/README.md

Initiate the data reading process from a local file. Requires the file path, Android context, and a desired database filename.

```kotlin
val file = File(requireContext (). filesDir.absolutePath + "/hubei-latest.osm.pbf")
reader.readData(file, requireContext (), "hubei")
	//filename	context		database filename(excepted)
```

--------------------------------

### Read Data from Uri

Source: https://github.com/sun-jiao/osmunda/blob/master/README.md

Initiate the data reading process from an Android Uri. Requires the Uri, Android context, and a desired database filename.

```kotlin
reader.readData(uri, requireContext (), "hubei")
	//android.net.Uri   context     database filename(excepted)
```

--------------------------------

### Configure Import Options

Source: https://github.com/sun-jiao/osmunda/blob/master/README.md

Optionally, configure the OsmosisReader to include relation and way data. If not specified, these are excluded by default.

```kotlin
reader.options.add (ImportOption.INCLUDE_RELATIONS) // Import relationa data
```

```kotlin
reader.options.add (ImportOption.INCLUDE_WAYS) // Import ways data
```

--------------------------------

### Forward Geocoding with BoundingBox

Source: https://context7.com/sun-jiao/osmunda/llms.txt

Perform forward geocoding using an osmdroid BoundingBox object, ideal for searching within the currently visible map area. Requires osmdroid library.

```kotlin
import moe.sunjiao.osmunda.geocoder.Geocoder
import org.osmdroid.util.BoundingBox
import org.osmdroid.views.MapView

val database = Osmunda(context).getDatabaseByName("hubei")
val geocoder = Geocoder(database)

// Get bounding box from current map view
val mapView: MapView = // your MapView instance
val boundingBox: BoundingBox = mapView.boundingBox

// Search within visible map area
val results = geocoder.search(
    "Hospital",
    20,              // Limit
    0,               // Offset
    boundingBox      // Search bounds from map
)

results.forEach { result ->
    println("${result.name} at (${result.lat}, ${result.lon})")
}
```

--------------------------------

### Osmunda - Database Management

Source: https://context7.com/sun-jiao/osmunda/llms.txt

Provides utilities for managing imported OSM databases, including listing available databases and retrieving specific databases for geocoding.

```APIDOC
## Osmunda - Database Management

### Description
The `Osmunda` class provides utilities for managing imported OSM databases, including listing all available databases and retrieving specific databases by name for geocoding operations.

### Method
`getDatabaseDir`, `getDatabaseList`, `getDatabaseByName`

### Endpoint
N/A (This is a library class, not an API endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```kotlin
import moe.sunjiao.osmunda.Osmunda
import android.database.sqlite.SQLiteDatabase
import java.io.File

val osmunda = Osmunda(context)

// Get the directory where OSM databases are stored
val databaseDir: File = osmunda.getDatabaseDir()

// List all imported OSM databases
val databases: Array<File>? = osmunda.getDatabaseList()
databases?.forEach { file ->
    println("Available database: ${file.name}")
}

// Open a specific database by name (without .sqlite extension)
val hubeiDatabase: SQLiteDatabase = osmunda.getDatabaseByName("hubei")
```

### Response
#### Success Response (200)
- **databaseDir** (File) - The directory where OSM databases are stored.
- **databases** (Array<File>?) - An array of File objects representing the available OSM databases, or null if none are found.
- **hubeiDatabase** (SQLiteDatabase) - An SQLiteDatabase object for the specified database name.

#### Response Example
```json
{
  "databaseDir": "/data/user/0/com.example.app/databases",
  "databases": [
    "hubei.sqlite",
    "region-data.sqlite"
  ],
  "hubeiDatabase": { /* SQLiteDatabase object */ }
}
```
```

--------------------------------

### Add JitPack Repository to Project Gradle

Source: https://github.com/sun-jiao/osmunda/blob/master/README.md

Include the JitPack repository in your project's build.gradle file to access Osmunda library versions.

```gradle
allprojects {
	repositories {
		...
		maven { url 'https://jitpack.io' }
	}
}
```

--------------------------------

### Import OSM Data from Uri using OsmosisReader

Source: https://context7.com/sun-jiao/osmunda/llms.txt

Initialize OsmosisReader and use it to read OSM data from an Android Uri, which is useful for importing files selected via the system file picker or content providers. The reader automatically detects the file type.

```kotlin
import moe.sunjiao.osmunda.reader.OsmosisReader
import moe.sunjiao.osmunda.reader.Reader
import android.net.Uri

val reader: Reader = OsmosisReader()

// Read OSM data from a content Uri (e.g., from file picker)
val uri: Uri = // Uri from Intent.ACTION_OPEN_DOCUMENT or similar
reader.readData(uri, context, "region-data")

// The reader automatically detects file type from Uri display name
// Supported formats: .pbf (fastest), .bz2, .gz
```

--------------------------------

### Configure Osmunda Data Import Options in Kotlin

Source: https://context7.com/sun-jiao/osmunda/llms.txt

Use the `ImportOption` enum to control which OSM data types are imported by `OsmosisReader`. By default, only nodes are imported. Including ways and relations increases database size but provides more complete geocoding data.

```kotlin
import moe.sunjiao.osmunda.reader.OsmosisReader
import moe.sunjiao.osmunda.model.ImportOption

val reader = OsmosisReader()

// Import only nodes (default behavior, smallest database)
// No additional options needed

// Import nodes and ways (medium database size)
reader.options.add(ImportOption.INCLUDE_WAYS)

// Import nodes, ways, and relations (largest database, most complete data)
reader.options.add(ImportOption.INCLUDE_WAYS)
reader.options.add(ImportOption.INCLUDE_RELATIONS)

// Storage example for Hubei Province:
// - PBF file: 11.64 MiB
// - SQLite database: ~274 MiB (approximately 16.78x the PBF size)
```

--------------------------------

### ImportOption - Configure Data Import

Source: https://context7.com/sun-jiao/osmunda/llms.txt

The `ImportOption` enum allows configuration of which OpenStreetMap data types (nodes, ways, relations) are imported into the database. This affects database size and the completeness of geocoding results.

```APIDOC
## ImportOption - Configure Data Import

### Description
The `ImportOption` enum controls which OSM data types are imported. By default, only nodes are imported. Adding `INCLUDE_WAYS` and `INCLUDE_RELATIONS` increases storage requirements but enables more complete geocoding results.

### Method
This is an enum used to configure options for `OsmosisReader`.

### Endpoint
N/A (This is a client-side library configuration)

### Parameters
This enum is used to add options to the `OsmosisReader`.

#### Options for `OsmosisReader`:
- **`ImportOption.INCLUDE_WAYS`**: Includes way data in the import.
- **`ImportOption.INCLUDE_RELATIONS`**: Includes relation data in the import.

### Request Example
```kotlin
import moe.sunjiao.osmunda.reader.OsmosisReader
import moe.sunjiao.osmunda.model.ImportOption

val reader = OsmosisReader()

// Import only nodes (default behavior, smallest database)
// No additional options needed

// Import nodes and ways (medium database size)
reader.options.add(ImportOption.INCLUDE_WAYS)

// Import nodes, ways, and relations (largest database, most complete data)
reader.options.add(ImportOption.INCLUDE_WAYS)
reader.options.add(ImportOption.INCLUDE_RELATIONS)
```

### Response
N/A (This configuration affects the import process, not a direct response)

### Storage Example
- **PBF file**: 11.64 MiB
- **SQLite database (Hubei Province)**: ~274 MiB (approximately 16.78x the PBF size)
```

--------------------------------

### Forward Geocoding with Geographic Bounds

Source: https://context7.com/sun-jiao/osmunda/llms.txt

Use Geocoder.search to convert location names to coordinates, optionally within specified latitude/longitude bounds. Supports pagination with limit and offset.

```kotlin
import moe.sunjiao.osmunda.Osmunda
import moe.sunjiao.osmunda.geocoder.Geocoder
import moe.sunjiao.osmunda.model.SearchResult

val database = Osmunda(context).getDatabaseByName("hubei")
val geocoder = Geocoder(database)

// Search for a location within Wuhan city bounds
// Parameters: query, limit, offset, maxLat, maxLon, minLat, minLon
val results: List<SearchResult> = geocoder.search(
    "Central China Normal University",  // Search query
    10,                                  // Limit: max results
    0,                                   // Offset: skip N results
    30.7324,                            // Max latitude (north)
    114.6589,                           // Max longitude (east)
    30.3183,                            // Min latitude (south)
    114.0588                            // Min longitude (west)
)

// Process search results
for (result in results) {
    println("Found: ${result.name}")
    println("Coordinates: ${result.lat}, ${result.lon}")
    println("Database ID: ${result.databaseId}")
}

// Search without geographic bounds (searches entire database)
val allResults: List<SearchResult> = geocoder.search(
    "Wuhan University",
    10,
    0
)
```

--------------------------------

### Add Osmunda to Android Project via Gradle

Source: https://context7.com/sun-jiao/osmunda/llms.txt

Include the JitPack repository and the Osmunda library dependency in your project's build.gradle files.

```groovy
// Add JitPack repository to your project build.gradle
allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}

// Add the dependency in your module build.gradle
dependencies {
    implementation 'moe.sunjiao:osmunda:1.5.0'
}
```

--------------------------------

### OsmosisReader.readData - Import OSM Data from File

Source: https://context7.com/sun-jiao/osmunda/llms.txt

Reads OpenStreetMap data files (pbf, bz2, gz) and imports them into a SQLite database. Supports configurable import options and progress tracking.

```APIDOC
## OsmosisReader.readData - Import OSM Data from File

### Description
Reads OpenStreetMap data files (pbf, bz2, gz formats) and imports them into a SQLite database. It supports configurable import options to include or exclude ways and relations data, and provides progress tracking during the import process.

### Method
`readData`

### Endpoint
N/A (This is a library method, not an API endpoint)

### Parameters
#### Path Parameters
- **osmFile** (File) - Required - The OSM data file to read.
- **context** (Context) - Required - The Android application context.
- **databaseName** (String) - Required - The name for the SQLite database (without extension).

#### Query Parameters
None

#### Request Body
None

### Request Example
```kotlin
import moe.sunjiao.osmunda.reader.OsmosisReader
import moe.sunjiao.osmunda.reader.Reader
import moe.sunjiao.osmunda.model.ImportOption
import java.io.File

// Initialize the OSM reader
val reader: Reader = OsmosisReader()

// Optional: Include relations and ways data (increases storage but enables more features)
reader.options.add(ImportOption.INCLUDE_RELATIONS)
reader.options.add(ImportOption.INCLUDE_WAYS)

// Optional: Configure commit frequency for batch inserts (default: 5000)
// Lower values use less memory, higher values are faster
(reader as OsmosisReader).commitFrequency = 5000

// Read OSM data from a file and import to SQLite database
val osmFile = File(context.filesDir.absolutePath + "/hubei-latest.osm.pbf")
reader.readData(osmFile, context, "hubei")  // Creates "hubei.sqlite" database

// Monitor import progress (0.0 to 1.0)
val progress: Double = reader.progress
val recordsRead: Long = reader.read
val recordsInserted: Long = reader.insert
val totalElements: Long = reader.elementCount
```

### Response
#### Success Response (200)
N/A (This method performs an import operation and does not return a value directly, but updates the database and progress properties.)

#### Response Example
None
```

--------------------------------

### Geocoding with BoundingBox

Source: https://github.com/sun-jiao/osmunda/blob/master/README.md

Perform a geocoding search using the bounding box of a MapView. This is useful for searching within the currently visible map area.

```kotlin
val box : BoundingBox = mapView.boundingBox
val list3: List<SearchResult> = Geocoder(hubeiDatabase).search("Central China Normal University", 10, 0, box)
```

--------------------------------

### Reverse Geocoding with GeoPoint

Source: https://github.com/sun-jiao/osmunda/blob/master/README.md

Perform a reverse geocoding search using an Osmdroid GeoPoint object. LIMIT and OFFSET can be specified.

```kotlin
val geoPoint : GeoPoint = GeoPoint(30.51910, 114.35775)
val list3: List<SearchResult> = ReverseGeocoder(hubeiDatabase).search(geoPoint, 100, 0)
```

--------------------------------

### Reverse Geocoding with IGeoPoint

Source: https://github.com/sun-jiao/osmunda/blob/master/README.md

Perform a reverse geocoding search using an IGeoPoint object, such as the map center from a MapView. LIMIT and OFFSET can be specified.

```kotlin
val iGeoPoint : IGeoPoint = mapView.mapCenter
val list4: List<SearchResult> = ReverseGeocoder(hubeiDatabase).search(iGeoPoint, 100, 0)
```

--------------------------------

### Geocoding with Latitude/Longitude Range

Source: https://github.com/sun-jiao/osmunda/blob/master/README.md

Perform a geocoding search for a specific address within a defined geographical bounding box (latitude and longitude). LIMIT and OFFSET can also be specified.

```kotlin
val hubeiDatabase: SQLiteDatabase = Osmunda(requireContext()).getDatabaseByName("hubei")
val list: List<SearchResult> = Geocoder(hubeiDatabase).search("Central China Normal University", 10, 0, 30.7324, 114.6589, 30.3183, 114.0588)
```

--------------------------------

### Add Osmunda Dependency to App Gradle

Source: https://github.com/sun-jiao/osmunda/blob/master/README.md

Add the Osmunda library dependency to your app's build.gradle file. Replace <VERSION> with the desired library version.

```gradle
dependencies {
        implementation 'moe.sunjiao:osmunda:<VERSION>'
}
```

--------------------------------

### Geocoder.search - Forward Geocoding with BoundingBox

Source: https://context7.com/sun-jiao/osmunda/llms.txt

Performs forward geocoding using an osmdroid BoundingBox object, ideal for searching within the currently visible map area.

```APIDOC
## Geocoder.search - Forward Geocoding with BoundingBox

### Description
Searches for a location name within the geographic bounds defined by an osmdroid BoundingBox object, commonly used for searching within the visible map area.

### Method
POST (or GET, depending on implementation, but example uses a method call)

### Endpoint
`/geocoder/search` (Conceptual endpoint, actual usage is via class method)

### Parameters
#### Query Parameters
- **query** (string) - Required - The location name to search for.
- **limit** (integer) - Optional - The maximum number of results to return.
- **offset** (integer) - Optional - The number of results to skip.
- **boundingBox** (BoundingBox) - Required - An osmdroid BoundingBox object defining the search area.

### Request Example
```kotlin
val boundingBox: BoundingBox = mapView.boundingBox
val results = geocoder.search(
    "Hospital",
    20,              // Limit
    0,               // Offset
    boundingBox      // Search bounds from map
)
```

### Response
#### Success Response (200)
- **results** (List<SearchResult>) - A list of search results matching the query within the specified bounding box.

#### Response Example
```json
[
  {
    "name": "Local Hospital",
    "lat": 30.5200,
    "lon": 114.3600,
    "databaseId": 67890
  }
]
```
```

--------------------------------

### Reverse Geocoding

Source: https://github.com/sun-jiao/osmunda/blob/master/README.md

Perform a reverse geocoding search using latitude and longitude coordinates. LIMIT and OFFSET can be specified.

```kotlin
val list: List<SearchResult> = ReverseGeocoder(hubeiDatabase).search(30.51910, 114.35775, 10, 0)
```

--------------------------------

### Reverse Geocoding with Location Object

Source: https://github.com/sun-jiao/osmunda/blob/master/README.md

Perform a reverse geocoding search using an Android Location object. LIMIT and OFFSET can be specified.

```kotlin
val location : Location = Location(GPS_PROVIDER)
val list2: List<SearchResult> = ReverseGeocoder(hubeiDatabase).search(location, 100, 0)
```

--------------------------------

### Reverse Geocoding with Coordinates

Source: https://context7.com/sun-jiao/osmunda/llms.txt

Use ReverseGeocoder.search to convert latitude and longitude coordinates into nearby place names. Results are sorted by distance from the query point and support pagination.

```kotlin
import moe.sunjiao.osmunda.Osmunda
import moe.sunjiao.osmunda.geocoder.ReverseGeocoder
import moe.sunjiao.osmunda.model.SearchResult

val database = Osmunda(context).getDatabaseByName("hubei")
val reverseGeocoder = ReverseGeocoder(database)

// Reverse geocode using latitude/longitude
val results: List<SearchResult> = reverseGeocoder.search(
    30.51910,    // Latitude
    114.35775,   // Longitude
    10,          // Limit
    0            // Offset
)

// Results are sorted by distance from query point
for (result in results) {
    println("Nearby: ${result.name}")
    println("Location: ${result.lat}, ${result.lon}")
}
```

--------------------------------

### Geocoding Without Range

Source: https://github.com/sun-jiao/osmunda/blob/master/README.md

Perform a geocoding search across the entire database without specifying a geographical range. LIMIT and OFFSET can still be used.

```kotlin
val list2: List<SearchResult> = Geocoder(hubeiDatabase).search("Central China Normal University", 10, 0)
```

--------------------------------

### OsmosisReader.readData - Import OSM Data from Uri

Source: https://context7.com/sun-jiao/osmunda/llms.txt

Reads OpenStreetMap data from an Android Uri and imports it into a SQLite database. Useful for importing files selected by the user.

```APIDOC
## OsmosisReader.readData - Import OSM Data from Uri

### Description
The reader also accepts Android Uri objects, allowing users to select OSM files through the system file picker or content providers. This is useful for importing data files that users download or store in external storage.

### Method
`readData`

### Endpoint
N/A (This is a library method, not an API endpoint)

### Parameters
#### Path Parameters
- **uri** (Uri) - Required - The Android Uri of the OSM data file.
- **context** (Context) - Required - The Android application context.
- **databaseName** (String) - Required - The name for the SQLite database (without extension).

#### Query Parameters
None

#### Request Body
None

### Request Example
```kotlin
import moe.sunjiao.osmunda.reader.OsmosisReader
import moe.sunjiao.osmunda.reader.Reader
import android.net.Uri

val reader: Reader = OsmosisReader()

// Read OSM data from a content Uri (e.g., from file picker)
val uri: Uri = // Uri from Intent.ACTION_OPEN_DOCUMENT or similar
reader.readData(uri, context, "region-data")

// The reader automatically detects file type from Uri display name
// Supported formats: .pbf (fastest), .bz2, .gz
```

### Response
#### Success Response (200)
N/A (This method performs an import operation and does not return a value directly.)

#### Response Example
None
```

--------------------------------

### Geocoder.search - Forward Geocoding with Geographic Bounds

Source: https://context7.com/sun-jiao/osmunda/llms.txt

Performs forward geocoding by searching for a location name within specified latitude and longitude bounds. Supports pagination with limit and offset.

```APIDOC
## Geocoder.search - Forward Geocoding with Geographic Bounds

### Description
Converts location names to geographic coordinates with support for bounded searches within specified latitude/longitude ranges and pagination.

### Method
POST (or GET, depending on implementation, but example uses a method call)

### Endpoint
`/geocoder/search` (Conceptual endpoint, actual usage is via class method)

### Parameters
#### Query Parameters
- **query** (string) - Required - The location name to search for.
- **limit** (integer) - Optional - The maximum number of results to return.
- **offset** (integer) - Optional - The number of results to skip.
- **maxLat** (double) - Optional - The maximum latitude for the search bounds.
- **maxLon** (double) - Optional - The maximum longitude for the search bounds.
- **minLat** (double) - Optional - The minimum latitude for the search bounds.
- **minLon** (double) - Optional - The minimum longitude for the search bounds.

### Request Example
```kotlin
val results: List<SearchResult> = geocoder.search(
    "Central China Normal University",  // Search query
    10,                                  // Limit: max results
    0,                                   // Offset: skip N results
    30.7324,                            // Max latitude (north)
    114.6589,                           // Max longitude (east)
    30.3183,                            // Min latitude (south)
    114.0588                            // Min longitude (west)
)
```

### Response
#### Success Response (200)
- **results** (List<SearchResult>) - A list of search results, each containing name, lat, lon, and databaseId.

#### Response Example
```json
[
  {
    "name": "Central China Normal University",
    "lat": 30.51910,
    "lon": 114.35775,
    "databaseId": 12345
  }
]
```
```

--------------------------------

### Retrieve Full Address Details

Source: https://github.com/sun-jiao/osmunda/blob/master/README.md

Iterate through a list of results and extract various components of a full address using the `toAddress()` method. Access individual address fields like country, city, street, and postcode.

```kotlin
for (result in list) {
	val address : Address = result.toAddress()
	val fullAddress : String = address.fullAddress   // full address
	val country : String = address.country  // country
	val state : String = address.state  // province or state
	val city : String = address.city  // city
	val county : String = address.county  // district, county
	val town : String = address.town  // little town
	val street : String = address.street  // road, street
	housenumber : String = address.housenumber  // house number
	val neighbourhood : String = address.neighbourhood  // community, school, institution, village, etc.
	val housename : String = address.housename  // 
	val postcode : String = address.postcode  // postcode
	val phone : String = address.phone  // phone number
	val website : String = address.website  // website
}
```

--------------------------------

### Set Commit Frequency

Source: https://github.com/sun-jiao/osmunda/blob/master/README.md

Set the commit frequency for database insertions. The default value is 5,000. Adjust this to control how often data is committed to the SQLite database.

```kotlin
(reader as OsmosisReader).commitFrequency = 5000
```

--------------------------------

### ReverseGeocoder.search - Reverse Geocoding with Coordinates

Source: https://context7.com/sun-jiao/osmunda/llms.txt

Performs reverse geocoding by converting geographic coordinates (latitude, longitude) into nearby place names. Results are sorted by distance.

```APIDOC
## ReverseGeocoder.search - Reverse Geocoding with Coordinates

### Description
Converts geographic coordinates (latitude and longitude) into nearby place names. Results are sorted by distance from the query point and support pagination.

### Method
POST (or GET, depending on implementation, but example uses a method call)

### Endpoint
`/reversegeocoder/search` (Conceptual endpoint, actual usage is via class method)

### Parameters
#### Query Parameters
- **latitude** (double) - Required - The latitude of the location.
- **longitude** (double) - Required - The longitude of the location.
- **limit** (integer) - Optional - The maximum number of results to return.
- **offset** (integer) - Optional - The number of results to skip.

### Request Example
```kotlin
val results: List<SearchResult> = reverseGeocoder.search(
    30.51910,    // Latitude
    114.35775,   // Longitude
    10,          // Limit
    0            // Offset
)
```

### Response
#### Success Response (200)
- **results** (List<SearchResult>) - A list of nearby search results, sorted by distance, each containing name, lat, lon, and databaseId.

#### Response Example
```json
[
  {
    "name": "Nearby Landmark",
    "lat": 30.51950,
    "lon": 114.35700,
    "databaseId": 11223
  }
]
```
```

--------------------------------

### Convert SearchResult to Address Object in Kotlin

Source: https://context7.com/sun-jiao/osmunda/llms.txt

Use the `toAddress()` method on a `SearchResult` object to obtain a detailed `Address` object. Access individual components like country, state, city, and street. Note that this operation can be CPU-intensive and should be performed on-demand.

```kotlin
import moe.sunjiao.osmunda.geocoder.ReverseGeocoder
import moe.sunjiao.osmunda.model.SearchResult
import moe.sunjiao.osmunda.model.Address

val database = Osmunda(context).getDatabaseByName("hubei")
val results = ReverseGeocoder(database).search(30.51910, 114.35775, 10, 0)

for (result in results) {
    // Convert search result to detailed address
    val address: Address = result.toAddress()

    // Access individual address components
    println("Full Address: ${address.fullAddress}")
    println("Name: ${address.name}")
    println("Country: ${address.country}")
    println("State/Province: ${address.state}")
    println("City: ${address.city}")
    println("County/District: ${address.county}")
    println("Town: ${address.town}")
    println("Street: ${address.street}")
    println("House Number: ${address.housenumber}")
    println("House Name: ${address.housename}")
    println("Neighbourhood: ${address.neighbourhood}")
    println("Postcode: ${address.postcode}")
    println("Phone: ${address.phone}")
    println("Website: ${address.website}")
    println("Coordinates: ${address.latitude}, ${address.longitude}")
}

// Note: Getting full address is CPU-intensive (0.3-3 seconds per result)
// Retrieve addresses on-demand rather than for entire result lists
```

--------------------------------

### ReverseGeocoder.search - Reverse Geocoding with Location Objects

Source: https://context7.com/sun-jiao/osmunda/llms.txt

Performs reverse geocoding using Android Location objects or osmdroid GeoPoint/IGeoPoint objects, facilitating integration with GPS and map views.

```APIDOC
## ReverseGeocoder.search - Reverse Geocoding with Location Objects

### Description
Performs reverse geocoding by accepting various location object types, including Android `Location`, osmdroid `GeoPoint`, and `IGeoPoint` (like map center), making it versatile for different data sources.

### Method
POST (or GET, depending on implementation, but example uses a method call)

### Endpoint
`/reversegeocoder/search` (Conceptual endpoint, actual usage is via class method)

### Parameters
#### Query Parameters
- **locationObject** (Location | GeoPoint | IGeoPoint) - Required - The location object representing the coordinates.
- **limit** (integer) - Optional - The maximum number of results to return.
- **offset** (integer) - Optional - The number of results to skip.

### Request Example
```kotlin
// Using Android Location
val location = Location(LocationManager.GPS_PROVIDER).apply { ... }
val fromLocation = reverseGeocoder.search(location, 100, 0)

// Using osmdroid GeoPoint
val geoPoint = GeoPoint(30.51910, 114.35775)
val fromGeoPoint = reverseGeocoder.search(geoPoint, 100, 0)

// Using map center (IGeoPoint)
val mapCenter: IGeoPoint = mapView.mapCenter
val fromMapCenter = reverseGeocoder.search(mapCenter, 100, 0)
```

### Response
#### Success Response (200)
- **results** (List<SearchResult>) - A list of nearby search results, sorted by distance, each containing name, lat, lon, and databaseId.

#### Response Example
```json
[
  {
    "name": "Current Location Area",
    "lat": 30.51910,
    "lon": 114.35775,
    "databaseId": 44556
  }
]
```
```

--------------------------------

### Reverse Geocoding with Location Objects

Source: https://context7.com/sun-jiao/osmunda/llms.txt

Reverse geocode using Android Location objects or osmdroid GeoPoint/IGeoPoint types. This integrates easily with GPS data and map interactions.

```kotlin
import moe.sunjiao.osmunda.geocoder.ReverseGeocoder
import android.location.Location
import android.location.LocationManager
import org.osmdroid.util.GeoPoint
import org.osmdroid.api.IGeoPoint
import org.osmdroid.views.MapView

val database = Osmunda(context).getDatabaseByName("hubei")
val reverseGeocoder = ReverseGeocoder(database)

// Using Android Location (from GPS)
val location = Location(LocationManager.GPS_PROVIDER).apply {
    latitude = 30.51910
    longitude = 114.35775
}
val fromLocation = reverseGeocoder.search(location, 100, 0)

// Using osmdroid GeoPoint
val geoPoint = GeoPoint(30.51910, 114.35775)
val fromGeoPoint = reverseGeocoder.search(geoPoint, 100, 0)

// Using map center (IGeoPoint)
val mapView: MapView = // your MapView instance
val mapCenter: IGeoPoint = mapView.mapCenter
val fromMapCenter = reverseGeocoder.search(mapCenter, 100, 0)

// All methods return the same List<SearchResult> type
```
Tokens:
Raw