jensostertag/geocoding-util

A simple PHP Library for the Nominatim Geocoding API

1.0.0 2023-07-14 05:20 UTC

Requires

• php: >=8.0.0
• jensostertag/curl-adapter: 1.0.0

GPL-2.0-only

• Jens Ostertag

• nominatim
• geocode

README

This is a simple PHP library to (reverse-)geocode addresses with the Nominatim API.

Legal Note: This library uses the Nominatim API. Please read the Terms of Use before using it and comply with them.

Data from OpenStreetMap is licensed under ODbL.

This library uses the Curl-Adapter library to send requests to the Nominatim API.

The Curl-Adapter library is licensed under the MIT License. (c) 2023 Jens Ostertag

Installation

To install this library, include it in your project using composer:

{
    "require": {
        "jensostertag/geocoding-util": "1.0.0"
    }
}

Usage

Geocode an address to coordinates

The following example shows how to geocode an address to coordinates:

<?php

use jensostertag\Geocoding\Geocoding;

$geocoding = new Geocoding();
$geocoding->setStreet("James-Franck-Ring")
          ->setHouseNumber("1")
          ->setCity("Ulm")
          ->setZipCode("89081")
          ->setCountry("Germany");
$coordinates = $geocoding->getCoordinates();
$lat = $coordinates["latitude"];
$lng = $coordinates["longitude"];

The above example will return the following coordinates:

{
    "latitude": 48.4253584,
    "longitude": 9.956179
}

Reverse-geocode coordinates to an address

The following example shows how to reverse-geocode coordinates to an address:

<?php

use jensostertag\Geocoding\Geocoding;
    
$geocoding = new Geocoding();
$geocoding->setCoordinates(48.4253584, 9.956179)
          ->toAddress();
$address = $geocoding->getAddress();
$street = $address["street"];
$houseNumber = $address["houseNumber"];
$city = $address["city"];
$zipCode = $address["zipCode"];
$country = $address["country"];
$formattedAddress = $geocoding->getFormattedAddress();

The above example will return the following address:

{
    "street": "James-Franck-Ring",
    "houseNumber": null,
    "city": "Ulm",
    "zipCode": "89081",
    "country": "Deutschland"
}

The formatted address will also be an array with two formatting options, inline and with \n line breaks:

{
    "inline": "James-Franck-Ring, 89081 Ulm, Deutschland (DE)",
    "lineBreaks": "James-Franck-Ring\n89081 Ulm\nDeutschland (DE)"
}

Setting a custom user agent

You might want to set a custom user agent for your requests towards the Nominatim API to identify your application. To do that, use

<?php

use jensostertag\Geocoding\Geocoding;

Geocoding::setUserAgent("MyApplication/1.0");

If you do not set a custom user agent, the default will be

Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 Firefox/109.0

Setting a custom Nominatim API URL

The public Nominatim API is very limited in the amount of requests you can send. If you want to use your own Nominatim API instance, you can set a custom URL for the API. To do that, use

<?php

use jensostertag\Geocoding\Geocoding;

Geocoding::setApiUrl("https://nominatim.mydomain.com");