Skip to main content
An itinerary builder needs more than an attractive thumbnail. It needs a photo of the intended place, a file that fits the layout, and the source and credit information that should travel with it. This example prepares a review queue for a destination cover image. It uses Lightdrift’s API to request five candidates and keeps each complete result alongside its query ID. It leaves the final choice to the person reviewing the itinerary. The example brief is an exterior photo of Old Point Loma Lighthouse in San Diego. This is a sample brief, not a claim that a particular result is available. A search result may depict a different lighthouse, have insufficient resolution, or need license conditions your layout cannot accommodate.

Run a three-stop itinerary example

For a repeatable workflow, download the runnable San Diego itinerary example. It makes three sequential location/activity searches, supports a no-network dry run, and preserves the complete response for each stop, including rights and any degraded or relaxed metadata. The briefs are illustrative; verify each candidate’s actual location and source/license conditions before use. Follow the README to keep the API key in your backend environment and check account entitlement before live execution.

Request candidates

Use Python 3 and a Lightdrift API key from your dashboard. Set LIGHTDRIFT_API_KEY through your development environment’s secret controls; don’t paste it into source code or a public comment. Save the following as itinerary_images.py:
Run it once:
Each successful search currently costs 0.005(0.005 (5 per 1,000 searches). Asking for five results is one search, not five searches. Confirm the current price before running. The script makes one request and does not retry automatically; a timeout can leave you unsure whether the search completed. Check your account usage before repeating it. The request uses documented search controls: landscape orientation, a requested minimum width, and source-declared commercial and derivative permissions. These filters narrow the search; they do not approve the final use. The response can report relaxed filters or degraded ranking, so the queue retains those fields.

Review before attaching

Every candidate stays marked needs_review. The script preserves the original result, including asset_id, file, thumb, dimensions, source, and the full rights object. It also retains query_id to connect the selection with the search. See the response reference. For each candidate:
  1. Open the preview and source page. Confirm that it depicts the intended landmark; a title or ranking score is not identity verification. Do not use a generic destination image to imply it depicts a booked hotel or supplier property.
  2. Check the actual width and height against your cover layout, including the proposed crop. Inspect relaxed and degraded; do not silently turn a short result list into permission to use any image.
  3. Read the source declaration and the complete rights object, including license_verbatim, commercial, derivatives, share_alike, attribution_required, attribution, provenance_url, and basis. Treat missing or null information as unresolved. If attribution is required but absent, hold that candidate.
  4. Carry the required credit and source/license references into the rendered itinerary and any exported version. Check applicable conditions for the crop or other modifications. Lightdrift reports the source’s rights declarations; it does not clear every possible use. See Rights answers.
Store the selected image’s metadata with the itinerary, rather than saving only its file URL. If your app renders titles or attribution, render them as text rather than trusted HTML. Lightdrift documents tracked file URLs that redirect to time-limited download links; follow redirects when fetching and avoid treating the final signed URL as a permanent asset address. If no candidate passes review, leave the cover unset and revise the brief or use a suitable image you already have permission to use. That outcome is useful feedback, too.

Try one real itinerary brief

Open Lightdrift and try this with one destination brief from your own workflow. Record whether you found a candidate you could actually use, what credit you carried through, and what stopped you if none qualified. A successful API response alone does not establish a successful image choice. Verification note: The request fields were checked against the live OpenAPI schema on September 26, 2026. Local checks exercised response preservation, empty results, missing credentials, and failure handling with synthetic fixtures. This example has not been tested with an authenticated live search and makes no retrieval-quality or latency claim.