# Public property map locations

**Live API contract.** Preview and production API revision `a91bd6b92d36941b66d356bcd1ecf884391a458e` publishes the nullable coordinate pair below. Authenticated preview responses were verified; production health and public schema were verified. See [rollout verification](./listing-card-rollout-verification.md) for evidence and limits.

## Affiliate contract

`mapLocation` is either an exact public property coordinate pair or `null`. There are no `status` or `precision` fields, and approximate positions are not supported.

```json
{
  "mapLocation": {
    "latitude": 33.088338,
    "longitude": -116.590737
  },
  "timeZone": "America/Los_Angeles"
}
```

This location excerpt uses Hummingbird’s saved preview coordinates. Consumers must use their API response rather than hardcode this example.

When there is no confirmed exact public location:

```json
{"mapLocation": null, "timeZone": "America/Los_Angeles"}
```

If `mapLocation` is present, plot it. If it is `null`, keep the listing card and omit its pin. Do not substitute a town center or obtain coordinates from private owner addresses. Both coordinates are finite WGS84 degrees. Lookup accepts high-confidence rooftop matches only; estimated/interpolated matches are not offered for confirmation. Existing approximate records return `null` and are not relabeled as exact.

Date-free `GET /api/travel/listings`, direct `GET /api/travel/listings/{listingId}`, combined search and batch availability cards use the same saved property position. No extra content request is needed for catalog pins. Rentals at one property can share the position while retaining their own listing IDs. Location presentation does not change eligibility, blacklists, prices, availability, pagination, booking attribution or no-store headers.

### Consumer update

Replace checks of `mapLocation.status` and `mapLocation.precision` with a null check on `mapLocation`. The nullable coordinate pair replaces the previous location object. Property stores only `publicLatitude` and `publicLongitude` for its public position. The retired status, precision, source and update-audit columns are removed from owner responses as well. Owner authorization and signed address confirmation remain enforced without storing these extra attributes. See [response schema](./travel-listings.schema.json) and [rollout evidence](./listing-card-rollout-verification.md) for the checked deployment revision.

### Hummingbird preview record

Authenticated catalog and direct-content requests on November 13, 2026 at 10:28:15–10:28:20 PM PST (`America/Los_Angeles`, offset `-08:00`) verified revision `a91bd6b92d36941b66d356bcd1ecf884391a458e`. Both image modes returned Hummingbird’s saved coordinates `33.088338, -116.590737` as the exact pair above, with no location status/precision fields. Direct content matched the catalog. These are observed saved property values, not illustrative coordinates or implementation defaults.

The owner does not need to reconfirm an unchanged, already confirmed exact position for this contract simplification. Changing the address still requires confirmation of the new pin. Withdrawing a location still removes it from affiliate responses. These checks do not independently survey the physical location.

## Property setup and editing

1. Owner enters the property's street address, city, state, postal code and country in setup or Property → Address.
2. **Find address on map** requests candidates from Wikiup's server. No coordinate entry is required. Multiple address matches can be selected; lookup failure has a retry path.
3. Inspect the embedded OpenStreetMap pin and check **This pin is correct. Publish this property location.**
4. Create the property or **Save changes**. Until that save, the candidate is only a draft. Owners may save their property without a public pin.
5. Changing the address clears a previous published point before the new address is written; the new point requires fresh confirmation. Existing properties are never silently geocoded/published.

## Owner API

`POST /api/properties/location-lookup` requires a user session, not an affiliate key. Body:

```json
{"propertyId":"PROPERTY_ID","address":{"line1":"100 Test Street","line2":"","city":"Julian","state":"CA","postalCode":"92036","country":"US"}}
```

Omit propertyId only during new-property setup. Existing property lookup requires ownership. Response: `{status:"found"|"no_match",candidates:[{formattedAddress,latitude,longitude,confirmation}]}`. Candidates are private. The opaque signed confirmation expires after 30 minutes and binds the owner, property (or new setup), full address, exact point. Do not log it. Invalid input is 422; denied access 401/403; request admission 429 with Retry-After; missing configuration/provider failure 503 with a safe error/code. One lookup/account/ten seconds, at most five requested candidates, six-second provider timeout, no background retries or lookup during affiliate searches.

Owner-adjusted pins may include optional `position: {latitude: 33.1, longitude: -116.6}` in the same lookup request. Omission performs provider lookup; null and invalid coordinates are rejected with 422. A supplied position is signed for the authenticated owner, address and property without calling the provider or consuming its lookup budget. The response shape is unchanged. New-property onboarding loads the address automatically, permits dragging or keyboard adjustment of the pin, and uses Create property as confirmation once the map and signed receipt are ready.

Save `publicLocationSelection` alongside the existing property POST/PUT payload: `{status:"published",confirmation:"OPAQUE_RECEIPT"}`, `{status:"withheld"}` or `{status:"missing"}`. These status values are transient commands, not stored Property fields. Both missing and withheld clear the coordinate pair; they do not create a stored disclosure state. Owner-only confirmation cannot be forged with client coordinates. A mismatched/expired receipt returns 409 before address writes. Alternatively, owner `PUT /api/properties/{id}/public-location` accepts the selection against the saved address. Owner GET returns `{mapLocation,timeZone}`. Both use private, no-store.

## Provider and rollout configuration

- Provider: [Geocodio](https://www.geocod.io/docs/), fixed server-side v2.1 forward geocoding endpoint. Authentication goes in the Authorization header, never browser JavaScript or a public URL.
- Set `GEOCODIO_API_KEY` securely in the target API environment file and corresponding GitHub environment secret `WIKIUP_API_ENV_FILE`. It is not a NEXT_PUBLIC variable. Configure preview and production separately; local development uses preview only. Do not paste the key in tickets/chat.
- From the repository root, after editing `wikiup-api/.env.production`, upload with `gh secret set --repo cosbor11/wikiup --env production WIKIUP_API_ENV_FILE < wikiup-api/.env.production`. For preview use `--env preview` and `.env.preview`. This uploads configuration only; it does not deploy. The deployed workflow’s **Sync Geocodio runtime binding** step reads the chosen environment file and patches only `GEOCODIO_API_KEY` as an encrypted Cloudflare Pages secret before deploying. It preserves unrelated secrets and the other environment. No separate dashboard upload is needed. A missing key leaves existing runtime configuration unchanged; removing the line is not a secret revocation.
- [Pricing](https://www.geocod.io/pricing): free daily allowance applies; configure provider billing/usage limits to prevent unintended paid use. Lookup happens only when an owner requests an address check, not on listing views or searches.
- Seven nullable Property fields store approval and coordinates. These schema additions have been published to both preview and production. Existing data is preserved; schema publication does not populate or approve property positions.
- The embedded map uses OpenStreetMap's hosted map with its attribution; only the candidate position is sent to that map service, not the street address or API credential.
- For a new environment, configure the provider key before address lookup. For an existing property, a non-null `mapLocation` already supplies its exact public position; no further setup is needed unless the address changes. Hummingbird’s observed preview status is documented above. Coverage across other properties and production records was not established by that check; directory coordinates and town centers must never be seeded as exact.

## Timestamps

Use each listing's validated IANA `timeZone` to display timestamps in property-local time, including offset and zone in diagnostic handoffs: `2026-11-13T12:25:48-08:00 (America/Los_Angeles)`. Do not present UTC-only timestamps to owners. Date-only check-in/check-out values remain unchanged. Internal audit instants and existing `generatedAt` transport fields retain their UTC representation for compatibility. Multi-property search metadata is a shared instant; render it separately in the relevant property's zone. A null timezone is explicitly unknown, never guessed from browser/server defaults.
