Your local-hour map looks ready to publish, except for the points near a timezone border. The coordinates are precise. The returned timezone looks perfectly respectable. You still have a reason to pause.
Coordinate mode assigns the timezone of a resolved nearby address or named place, which can fall across a timezone border from your submitted point.
That makes distanceMeters a measure of displacement to the match. It can't certify which side of a timezone boundary your original point occupies.
Which point does your timezone describe?
The geographic question changes halfway through the lookup.
submitted coordinate
|
v
nearest address or named place
|
v
timezone assigned to that place
A point-in-polygon operation asks which boundary contains your coordinate. Nearest-place matching asks which place resolves nearby, then supplies its timezone.
Those operations can agree without being equivalent.
The annoying part is that a plausible timezone identifier gives you no visible warning about the distinction. A schema validator can approve the row while your chart caption quietly overclaims what it represents.
Coverage ends where place resolution ends
The Actor needs a resolved place with a timezone. Open-ocean, unmapped or unclaimed locations may produce no record; unresolved inputs are identified in the run status instead of receiving a guessed assignment.
This is coverage through place resolution, rather than a promise of continuous geographic coverage.
Here are the fields that matter for this audit:
| Evidence | Fields | Interpretation |
|---|---|---|
| Submitted point | inputLocation |
The exact input that produced the row |
| Resolved point | location |
The matched place's coordinates |
| Match displacement | distanceMeters |
Distance from the submitted coordinate to the matched place, for coordinate lookups |
| Assignment | timezone |
The returned IANA timezone identifier |
| Review context |
placeName, formattedAddress, googleMapsUrl
|
Evidence for inspecting the match |
| Lookup timing |
scrapedAt, currentUtcTime, currentLocalTime
|
Lookup and current-time context, rather than the time of your activity event |
Unavailable fields are omitted. Place identifiers, country codes and categories are conditional, so their absence can't establish that a location belongs to no category or country.
The country setting biases place and address searches; it doesn't affect coordinates. Changing language changes returned names and addresses, rather than translating your query.
Example coordinate inputs make this cell runnable; replace locations with the points behind your map.
import json
import math
import os
import duckdb
import pandas as pd
from apify_client import ApifyClient
run_input = {
"mode": "coordinates",
"locations": [
{"lat": 40.7128, "lng": -74.006},
{"lat": 35.6762, "lng": 139.6503},
],
}
client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor(
"dataspryva/google-maps-timezone-and-local-time-lookup"
).call(run_input=run_input)
if run["status"] != "SUCCEEDED":
raise RuntimeError(f"Lookup requires review: {run['status']}")
items = client.dataset(run["defaultDatasetId"]).list_items().items
A successful status is a run-level condition. It doesn't establish a returned assignment for every submitted location.
Keep the submitted point beside the returned record
You need a submission ledger before you need a prettier map.
Duplicate coordinates are removed before lookup, so dataset rows aren't an activity denominator. If your activity table contains repeated events at the same coordinate, retain those events separately and attach the lookup results afterwards.
The next cell extracts the submitted point and preserves each returned record intact, including its resolved location when supplied. It accepts an input object or its JSON string representation; an unrecognised representation remains unparsed.
def parse_point(value):
if isinstance(value, str):
try:
value = json.loads(value)
except (ValueError, TypeError):
return (None, None)
if not isinstance(value, dict):
return (None, None)
try:
raw_lat, raw_lng = value.get("lat"), value.get("lng")
if isinstance(raw_lat, bool) or isinstance(raw_lng, bool):
return (None, None)
lat, lng = float(raw_lat), float(raw_lng)
except (TypeError, ValueError, OverflowError):
return (None, None)
if not (math.isfinite(lat) and math.isfinite(lng)):
return (None, None)
if not (-90 <= lat <= 90 and -180 <= lng <= 180):
return (None, None)
return (lat, lng)
matches = pd.DataFrame(items).reindex(columns=[
"inputLocation", "distanceMeters", "timezone",
"placeName", "formattedAddress", "googleMapsUrl",
])
parsed_points = matches["inputLocation"].map(parse_point)
matches["submitted_lat"] = parsed_points.map(lambda point: point[0])
matches["submitted_lng"] = parsed_points.map(lambda point: point[1])
matches["timezone"] = (
matches["timezone"].astype("string").str.strip().replace("", pd.NA)
)
matches["returned_record"] = pd.Series(
[json.dumps(item, ensure_ascii=False) for item in items],
dtype="string",
)
Keeping the complete record also avoids manufacturing coordinates from an address string. An attractive map pin is a poor substitute for a geographic object you can trace.
If input parsing fails, that's a reconciliation problem. It isn't evidence that the source failed to find the location.
Measure displacement without calling it accuracy
There's no universal match-distance threshold that proves a timezone assignment correct.
Even a short displacement can cross a nearby boundary. A longer displacement can remain within the same zone. Distance to a place and distance to a boundary are different measurements.
This cell parses numeric distance strings, retains unknown representations as missing, and creates analyst-chosen review bands.
def parse_distance(value):
if isinstance(value, bool) or not isinstance(value, (str, int, float)):
return None
try:
distance = float(value)
except (TypeError, ValueError, OverflowError):
return None
return distance if math.isfinite(distance) and distance >= 0 else None
matches["distance_m"] = (
matches["distanceMeters"].map(parse_distance).astype("Float64")
)
matches["displacement_band"] = pd.cut(
matches["distance_m"],
bins=[float("-inf"), 0, 100, 1000, float("inf")],
labels=["zero", "up_to_100_m", "100_to_1000_m", "over_1000_m"],
).astype("string").fillna("unavailable_or_unparsed")
The band edges organise inspection. They aren't geographic acceptance criteria.
These queries calculate displacement distributions and timezone counts on your pull, with missing distances kept visible.
diagnostic_rows = matches[
["timezone", "distance_m", "displacement_band"]
]
distance_summary = duckdb.sql("""
SELECT
displacement_band,
count(*) AS returned_rows,
count(timezone) AS rows_with_timezone,
count(*) - count(timezone) AS rows_without_timezone,
quantile_cont(distance_m, 0.5) AS median_distance_m,
quantile_cont(distance_m, 0.95) AS p95_distance_m
FROM diagnostic_rows
GROUP BY displacement_band
ORDER BY displacement_band
""").df()
timezone_counts = duckdb.sql("""
SELECT displacement_band, timezone, count(*) AS returned_rows
FROM diagnostic_rows
GROUP BY displacement_band, timezone
ORDER BY displacement_band, returned_rows DESC
""").df()
These are match diagnostics. Calling them an accuracy report would require evidence they don't contain.
Count the inputs your dataset can't account for
A distance distribution describes returned rows. It says nothing about locations absent from the dataset unless you reconcile against what you submitted.
The next cell compares unique submitted coordinates with parseable returned inputs and builds a review table containing the original point, assignment, match context and complete returned record. It creates linked_row as an audit marker before joining.
submitted = (
pd.DataFrame(run_input["locations"])[["lat", "lng"]]
.drop_duplicates()
.rename(columns={"lat": "submitted_lat", "lng": "submitted_lng"})
)
joinable_matches = matches.dropna(
subset=["submitted_lat", "submitted_lng"]
).copy()
joinable_matches["linked_row"] = True
review = submitted.merge(
joinable_matches,
on=["submitted_lat", "submitted_lng"],
how="left",
validate="one_to_many",
)
unlinked_records = matches.loc[
matches[["submitted_lat", "submitted_lng"]].isna().any(axis=1)
]
coverage_counts = pd.Series({
"submitted_unique_coordinates": len(submitted),
"returned_rows": len(matches),
"returned_rows_with_unparsed_input": len(unlinked_records),
"submitted_coordinates_without_linked_row": (
review["linked_row"].isna().sum()
),
"linked_rows_without_timezone": (
review["linked_row"].eq(True)
& review["timezone"].isna()
).sum(),
}, name="count")
“Without linked row” is deliberately cautious. It can reflect an unresolved lookup or a reconciliation issue; the run status and retained records provide the next evidence to inspect.
Don't quietly remove these inputs before calculating your chart's denominator. Missing assignments are part of the coverage statement, even when they make the caption less elegant.
Put the assignment method on the chart
For Google Maps Timezone & Local Time Lookup, a defensible caption distinguishes submitted coordinates from matched places.
A wording you can adapt is: “Activity grouped by local hour using timezone assignments for resolved nearby places. Unreconciled coordinates and unavailable match distances are reported separately.”
Then fill in the coverage counts your own pull computes. Label a displacement summary as displacement, rather than geographic correctness.
Your event timestamps need separate care. The returned offset and daylight-saving state describe lookup time. Applying that current offset to historical activity can shift events into the wrong local hour; conversion needs the event's actual timestamp and the relevant timezone rules.
A clean assignment table doesn't repair an incorrect time conversion.
A border audit needs another geographic source
The Actor follows the source's place and boundary data; it doesn't maintain a separate timezone boundary map.
To investigate the suspicious border points, compare assignments with a separately sourced timezone polygon dataset using the submitted coordinates. Keep that dataset's provenance, boundary version and treatment of disputed areas alongside the comparison.
A disagreement table needs both geographic objects: your submitted point and the resolved place. It also needs both timezone assignments and the returned map link, so you can inspect the disagreement without declaring either source authoritative.
The comparison can't certify the physical location of an activity event, repair imprecise coordinates or establish that a boundary dataset is current. It can identify which assignments depend on a geographic choice your chart might otherwise conceal.
A valid timezone identifier can still answer the wrong geographic question.
Drafted with AI assistance and reviewed for accuracy.
Top comments (0)