Tiger_Location_Adapter_Aws

@api · extends Tiger_Location_Adapter_Abstract

Tiger_Location_Adapter_Aws — AWS Location Service (Places) adapter.

Supports autocomplete (CAP_SUGGEST), forward geocoding (CAP_GEOCODE), and reverse geocoding (CAP_REVERSE) via the AWS Location Service "Places" APIs. The underlying place data is Esri/HERE-backed (whichever provider your Place Index is configured for) — so before this adapter does anything useful you must provision a Place Index in the AWS console (or via IaC) and name it in config (place_index). Without an index — or without credentials/region — every operation degrades gracefully to empty results ([]) / null rather than throwing.

Requests are POST JSON to places.geo.{region}.amazonaws.com, SigV4-signed for the geo service. The sibling S3 adapter (Tiger_Media_Storage_S3) leans on the aws-sdk-php client to sign for it; we don't pull the SDK in here (Location is a much smaller surface), so the SigV4 canonical-request → string-to-sign → signing-key → Authorization steps are replicated inline below (see _signedPost / _sigV4Headers). Credentials come from config (key/secret/token) and, when absent, fall back to the standard environment variables (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN) — the same env fallback the S3 adapter relies on.

Config (tiger.location.adapters.aws.*):

  • region : AWS region (e.g. 'us-east-1')
  • place_index : the AWS Location Service Place Index name
  • key : AWS access key id (else env AWS_ACCESS_KEY_ID)
  • secret : AWS secret access key (else env AWS_SECRET_ACCESS_KEY)
  • token : AWS session token (else env AWS_SESSION_TOKEN) — optional (STS creds)

Methods

capabilities()

capabilities(): array

The CAP_* operations this adapter supports (suggest, geocode, reverse).

Returns array — a list of CAP_* capability constants

suggest()

suggest(string $query, array $opts = []): array

Autocomplete a partial address. Returns Tiger_Location_Place[] of lightweight suggestions (label + optional PlaceId to feed a follow-up geocode). Empty on any error.

  • $query string — the partial address text
  • $opts array — options (e.g. 'country' to bias results)

Returns array

geocode()

geocode(string $query, array $opts = []): array

Geocode free text to structured address(es) with coordinates. Empty on any error.

  • $query string — the address text to geocode
  • $opts array — options (e.g. 'country' to bias results)

Returns array

reverse()

reverse(float $lat, float $lng, array $opts = []): ?Tiger_Location_Place

Reverse-geocode a coordinate to the nearest address. Null on any error / no match. Note AWS takes position as [longitude, latitude].

  • $lat float — the latitude
  • $lng float — the longitude
  • $opts array — provider options

Returns ?Tiger_Location_Place — the nearest place, or null on error / no match