timezone_location_get()

Purpose

timezone_location_get() is the procedural alias of DateTimeZone::getLocation(). It takes a DateTimeZone object and reports geographic information stored for that zone: a country code, a latitude, a longitude and a free-form comment. It is useful when you hold a zone identifier such as Europe/Prague and want to show a rough map position, group zones by country, or sanity-check user-supplied zone data.

Because it is only an alias, both spellings behave identically. Choose the procedural form when the surrounding code is procedural, and the method form when you already work with objects.

Signature

Parameters and defaults

There are no optional parameters and no defaults. Passing anything other than a DateTimeZone object raises a TypeError.

Return value and failure cases

On success the function returns an associative array with these keys, in this order:

• country_code: a two-letter country code, or a placeholder such as ?? when the zone has no country.
• latitude: a float.
• longitude: a float.
• comments: a string, often empty.

The function returns false when location data is not available for the object. A common case is a zone built from a fixed UTC offset such as +02:00, because that kind of zone is not a named identifier from the time zone database.

Example 1: reading country and coordinates

The coordinates are floats from the bundled time zone database, so this example rounds them before printing. That keeps the output stable and readable.

<?php
$tz = timezone_open('Europe/Prague');
$loc = timezone_location_get($tz);
echo json_encode([
    'country' => $loc['country_code'],
    'lat' => round($loc['latitude'], 2),
    'lon' => round($loc['longitude'], 2),
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), PHP_EOL;

{"country":"CZ","lat":50.08,"lon":14.43}

Example 2: the alias matches the method

Calling the function and calling the method on the same object gives equal results. The array shape is also easy to inspect through its keys.

<?php
$tz = new DateTimeZone('Asia/Tokyo');
$a = timezone_location_get($tz);
$b = $tz->getLocation();
echo json_encode([
    'same' => $a === $b,
    'keys' => array_keys($a),
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), PHP_EOL;

{"same":true,"keys":["country_code","latitude","longitude","comments"]}

Example 3: an offset zone has no location

A zone created from an offset does not name a place, so there is nothing to look up. Always be ready for false.

<?php
$tz = new DateTimeZone('+02:00');
var_dump(timezone_location_get($tz));

bool(false)

Edge cases

• Offsets and abbreviations. Zones created from offsets such as +02:00 carry no identifier, so expect false. Do not assume every DateTimeZone object can produce coordinates.
• Zones without a country. Some identifiers are not tied to a single country. For these the country code is a placeholder rather than a real ISO code, so do not feed it blindly into a country lookup.
• Precision. Latitude and longitude are floats derived from the database. Compare them with a tolerance or round them, and never rely on an exact decimal representation.
• Data changes. The values come from the time zone data bundled with your PHP build. A newer database can adjust comments or coordinates, so avoid hard-coding expected comment text.
• Empty comments. An empty comments string is normal and not an error.

Common mistakes

1. Indexing the result without checking for false. Reading $loc['country_code'] on a false value produces a warning and a null. Test with if ($loc === false) first.
2. Passing a string. The function wants a DateTimeZone object. Write timezone_location_get(timezone_open('UTC')), not timezone_location_get('UTC').
3. Treating the coordinates as an exact city centre. They are representative points for the zone, suitable for rough display only.
4. Confusing this with offsets. The function does not tell you the current UTC offset or daylight saving state. Use timezone_offset_get() or DateTimeZone::getOffset() for that.
5. Printing raw floats in tests. Raw float output can vary with ini settings and data versions. Round values or compare keys when you need predictable output.

Related functions

• DateTimeZone::getLocation(), the method this function aliases.
• timezone_open(), which creates the object to pass in.
• timezone_name_get(), which returns the zone identifier.
• timezone_offset_get(), which returns the offset in seconds for a given date.
• timezone_identifiers_list(), which lists valid identifiers.

Recap

timezone_location_get() accepts one DateTimeZone and returns either an array with country_code, latitude, longitude and comments, or false when no location data exists. It is exactly the same as DateTimeZone::getLocation(). Check for false, round coordinates before displaying them, and use other timezone functions when you need offsets rather than geography.