diff --git a/Makefile b/Makefile
index 050d3f0..72e92b9 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,5 @@
 .PHONY: lint test coverage
+.PHONY: e2e
 
 lint:
 	golangci-lint fmt
@@ -9,3 +10,6 @@ test:
 
 coverage:
 	./scripts/check-coverage.sh
+
+e2e:
+	go test -tags=e2e ./... -run TestE2E
diff --git a/README.md b/README.md
index c3c204e..865e55d 100644
--- a/README.md
+++ b/README.md
@@ -102,3 +102,19 @@ Enforce coverage:
 ```bash
 ./scripts/check-coverage.sh
 ```
+
+### E2E tests (optional)
+
+Real API tests (skipped unless you opt in):
+
+```bash
+export GOOGLE_PLACES_API_KEY="..."
+go test -tags=e2e ./... -run TestE2E
+```
+
+Optional env overrides:
+
+- `GOOGLE_PLACES_E2E_BASE_URL`
+- `GOOGLE_PLACES_E2E_QUERY`
+- `GOOGLE_PLACES_E2E_LANGUAGE`
+- `GOOGLE_PLACES_E2E_REGION`
diff --git a/e2e_test.go b/e2e_test.go
new file mode 100644
index 0000000..806fa42
--- /dev/null
+++ b/e2e_test.go
@@ -0,0 +1,70 @@
+//go:build e2e
+// +build e2e
+
+package goplaces
+
+import (
+	"context"
+	"os"
+	"testing"
+	"time"
+)
+
+func TestE2ESearchAndDetails(t *testing.T) {
+	apiKey := os.Getenv("GOOGLE_PLACES_API_KEY")
+	if apiKey == "" {
+		t.Skip("GOOGLE_PLACES_API_KEY not set")
+	}
+
+	query := os.Getenv("GOOGLE_PLACES_E2E_QUERY")
+	if query == "" {
+		query = "coffee in Seattle"
+	}
+	language := os.Getenv("GOOGLE_PLACES_E2E_LANGUAGE")
+	if language == "" {
+		language = "en"
+	}
+	region := os.Getenv("GOOGLE_PLACES_E2E_REGION")
+	if region == "" {
+		region = "US"
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	client := NewClient(Options{
+		APIKey:  apiKey,
+		BaseURL: os.Getenv("GOOGLE_PLACES_E2E_BASE_URL"),
+		Timeout: 10 * time.Second,
+	})
+
+	search, err := client.Search(ctx, SearchRequest{
+		Query:    query,
+		Limit:    1,
+		Language: language,
+		Region:   region,
+	})
+	if err != nil {
+		t.Fatalf("search error: %v", err)
+	}
+	if len(search.Results) == 0 {
+		t.Fatalf("expected search results")
+	}
+
+	placeID := search.Results[0].PlaceID
+	if placeID == "" {
+		t.Fatalf("expected place id")
+	}
+
+	details, err := client.DetailsWithOptions(ctx, DetailsRequest{
+		PlaceID:  placeID,
+		Language: language,
+		Region:   region,
+	})
+	if err != nil {
+		t.Fatalf("details error: %v", err)
+	}
+	if details.PlaceID == "" {
+		t.Fatalf("expected details place id")
+	}
+}