> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Braian551/viax/llms.txt
> Use this file to discover all available pages before exploring further.

# Geocoding

> Convert addresses to coordinates and vice versa

## Geocode Address

```
GET /map/geocode.php
```

Convert a street address to geographic coordinates (latitude/longitude).

### Query Parameters

<ParamField query="address" type="string" required>
  Street address to geocode (URL-encoded)
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Geocoding success status
</ResponseField>

<ResponseField name="location" type="object">
  Location with coordinates

  <Expandable title="location structure">
    <ResponseField name="latitud" type="number">
      Latitude in decimal degrees
    </ResponseField>

    <ResponseField name="longitud" type="number">
      Longitude in decimal degrees
    </ResponseField>

    <ResponseField name="direccion" type="string">
      Formatted address
    </ResponseField>

    <ResponseField name="ciudad" type="string">
      City name
    </ResponseField>

    <ResponseField name="pais" type="string">
      Country name
    </ResponseField>
  </Expandable>
</ResponseField>

### Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://76.13.114.194/map/geocode.php?address=Carrera%2015%20%2385-30%2C%20Bogot%C3%A1" \
    -H "Accept: application/json"
  ```

  ```dart Dart theme={null}
  import 'package:http/http.dart' as http;
  import 'dart:convert';

  Future<Map<String, dynamic>> geocodeAddress(String address) async {
    final encodedAddress = Uri.encodeComponent(address);
    final response = await http.get(
      Uri.parse('https://76.13.114.194/map/geocode.php?address=$encodedAddress'),
      headers: {'Accept': 'application/json'},
    );

    if (response.statusCode == 200) {
      final data = jsonDecode(response.body);
      if (data['success'] == true) {
        return data['location'];
      }
    }
    throw Exception('Failed to geocode address');
  }

  // Usage:
  final location = await geocodeAddress('Carrera 15 #85-30, Bogotá');
  print('Lat: ${location['latitud']}, Lng: ${location['longitud']}');
  ```

  ```javascript JavaScript theme={null}
  async function geocodeAddress(address) {
    const url = new URL('https://76.13.114.194/map/geocode.php');
    url.searchParams.append('address', address);
    
    const response = await fetch(url, {
      headers: { 'Accept': 'application/json' },
    });
    
    const data = await response.json();
    if (data.success) {
      return data.location;
    }
    throw new Error(data.message || 'Geocoding failed');
  }
  ```
</CodeGroup>

### Response Example

<CodeGroup>
  ```json Success theme={null}
  {
    "success": true,
    "location": {
      "latitud": 4.6814,
      "longitud": -74.0479,
      "direccion": "Carrera 15 #85-30",
      "ciudad": "Bogotá",
      "pais": "Colombia"
    }
  }
  ```

  ```json Address Not Found theme={null}
  {
    "success": false,
    "message": "No se pudo geocodificar la dirección"
  }
  ```
</CodeGroup>

***

## Reverse Geocode

```
GET /map/reverse_geocode.php
```

Convert geographic coordinates to a street address.

### Query Parameters

<ParamField query="lat" type="number" required>
  Latitude in decimal degrees
</ParamField>

<ParamField query="lng" type="number" required>
  Longitude in decimal degrees
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Reverse geocoding success status
</ResponseField>

<ResponseField name="location" type="object">
  Location with address information
</ResponseField>

### Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://76.13.114.194/map/reverse_geocode.php?lat=4.6814&lng=-74.0479" \
    -H "Accept: application/json"
  ```

  ```dart Dart theme={null}
  Future<Map<String, dynamic>> reverseGeocode(
    double lat,
    double lng,
  ) async {
    final response = await http.get(
      Uri.parse('https://76.13.114.194/map/reverse_geocode.php?lat=$lat&lng=$lng'),
      headers: {'Accept': 'application/json'},
    );

    if (response.statusCode == 200) {
      final data = jsonDecode(response.body);
      if (data['success'] == true) {
        return data['location'];
      }
    }
    throw Exception('Failed to reverse geocode');
  }

  // Usage:
  final location = await reverseGeocode(4.6814, -74.0479);
  print('Address: ${location['direccion']}');
  ```

  ```javascript JavaScript theme={null}
  async function reverseGeocode(lat, lng) {
    const response = await fetch(
      `https://76.13.114.194/map/reverse_geocode.php?lat=${lat}&lng=${lng}`,
      { headers: { 'Accept': 'application/json' } }
    );
    
    const data = await response.json();
    return data.success ? data.location : null;
  }
  ```
</CodeGroup>

### Response Example

```json Success theme={null}
{
  "success": true,
  "location": {
    "latitud": 4.6814,
    "longitud": -74.0479,
    "direccion": "Carrera 15 #85-30",
    "ciudad": "Bogotá",
    "pais": "Colombia"
  }
}
```

***

## Use Cases

### Address Input with Autocomplete

Geocode user-entered addresses:

```dart theme={null}
class AddressSearchController {
  Future<Location?> searchAddress(String query) async {
    try {
      final location = await geocodeAddress(query);
      return LocationModel.fromJson(location);
    } catch (e) {
      print('Geocoding error: $e');
      return null;
    }
  }
}
```

### Map Marker Click

Get address from map coordinates:

```dart theme={null}
void onMapClick(double lat, double lng) async {
  final location = await reverseGeocode(lat, lng);
  showDialog(
    context: context,
    builder: (context) => AlertDialog(
      title: Text('Ubicación'),
      content: Text(location['direccion']),
    ),
  );
}
```

### Current Location Display

Show user's current address:

```dart theme={null}
Future<String> getCurrentAddress() async {
  final position = await Geolocator.getCurrentPosition();
  final location = await reverseGeocode(
    position.latitude,
    position.longitude,
  );
  return location['direccion'];
}
```

***

## Colombian Address Format

Colombian addresses follow a specific format:

* **Calle/Carrera**: Street type
* **Number**: Street number
* **#**: Separator
* **Cross street**: Intersecting street
* **-**: Separator
* **Building number**: Specific building/house number

### Examples

* `Carrera 15 #85-30` - Career 15, at intersection with Street 85, building 30
* `Calle 72 #10-20` - Street 72, at intersection with Career 10, building 20
* `Diagonal 50 #25-15` - Diagonal 50, building at 25-15

***

## Error Responses

<ResponseField name="400" type="Bad Request">
  Invalid coordinates or missing address
</ResponseField>

<ResponseField name="404" type="Not Found">
  Address or coordinates could not be resolved
</ResponseField>

<ResponseField name="500" type="Internal Server Error">
  Geocoding service error
</ResponseField>

## Notes

<Note>
  The geocoding service uses OpenStreetMap or Google Maps API (depending on configuration). Ensure coordinates are within Colombia for best results.
</Note>

<Warning>
  Geocoding may have rate limits. Cache results when possible to avoid repeated API calls.
</Warning>

## See Also

* [Routing](/api/map/routing) - Calculate routes between locations
* [Location Sharing](/api/map/location-sharing) - Share real-time location