tauwahi / laravel

v1.0 2026-09-13 17:07 UTC

Requires

• php: ^8.4|^8.5

Requires (Dev)

• orchestra/testbench: ^11.2
• pestphp/pest: ^5.1

MIT

• Karl Valentin

Published on Packagist.org on 2026-09-13 17:35 UTC

README

A geocoding package for Laravel applications integrating with the Tauwahi (geo.kvis.de) Geocoding API.

Features

• Forward Geocoding (Search): Search addresses and places by text query with optional detailed address components.
• Reverse Geocoding: Resolve geographic coordinates (lat, lon) into address data.
• Lookup: Query one or multiple OpenStreetMap (OSM) IDs.

Requirements

• PHP 8.2+
• Laravel 11.0+ or compatible

Installation

You can install the package via Composer:

composer require tauwahi/laravel

Configuration

Required

Set your environment variables in your .env file:

GEOCODE_API_KEY=your_api_key_here

Optional

If you want to, you can publish the package configuration file using Artisan:

php artisan vendor:publish --provider="Tauwahi\Laravel\GeocodePackage\GeocodePackageServiceProvider" --tag="config"

This will create a config/geocode.php file:

return [
    'api_key' => env('GEOCODE_API_KEY'),
    'api_url' => env('GEOCODE_API_URL', 'https://geo.kvis.de/api/v1'),
    'timeout' => (int) env('GEOCODE_TIMEOUT', 10),
];

You can optionally configure a custom request timeout (in seconds):

GEOCODE_TIMEOUT=10

Usage

You can access the geocoding service via the Geocode facade.

Forward Geocoding (Search)

Search for a location using a text query.

use Tauwahi\Laravel\GeocodePackage\Facades\Geocode;

$addresses = Geocode::search('Alexanderplatz 1, Berlin', addressDetails: true);

Reverse Geocoding

Find the address for specific latitude and longitude coordinates. Returns an Address object.

use Tauwahi\Laravel\GeocodePackage\Facades\Geocode;

$address = Geocode::reverse(lat: 52.5200, lon: 13.4050);

echo $address->display_name;
echo $address->name;

Lookup by OSM ID

Retrieve address data for one or more OpenStreetMap (OSM) IDs. Returns an Illuminate\Support\Collection of Address objects.

use Tauwahi\Laravel\GeocodePackage\Facades\Geocode;

// Single OSM ID
$addresses = Geocode::lookup(67890);

// Multiple OSM IDs
$addresses = Geocode::lookup([67890, 98765]);

Models

Address

Represents a geocoded location with the following properties:

• place_id (int)
• licence (string)
• osm_type (string)
• osm_id (int)
• lat (float)
• lon (float)
• class (string)
• type (string)
• place_rank (int)
• importance (float)
• addresstype (string)
• name (string)
• display_name (string)
• boundingbox (array)
• address (?AddressDetails)

AddressDetails

Provides access to individual address components (e.g. road, house_number, city, postcode, state, country, country_code):

// Property access
$city = $address->address->city;

// Method access
$road = $address->address->get('road');

// Convert to array
$array = $address->address->toArray();

// JSON string representation
$json = (string) $address->address;

Testing

Run the test suite using Pest:

./vendor/bin/pest

License

This package is open-source software licensed under the MIT license.