# JamesEdition Search ## Overview | Property | Value | |----------|-------| | **Status** | active | | **Method** | `GET` | | **Endpoint** | `/v2/jamesedition/search` | | **Base URL** | `https://api.piloterr.com` | | **Credit Cost** | 1 credit per call | | **Documentation** | https://www.piloterr.com/library/jamesedition-search | ## Description Search JamesEdition luxury homes by keyword or by a results URL. ## Authentication - **Key Name:** `x-api-key` - **Location:** HTTP Header - **Get an API key:** https://app.piloterr.com/register ## Example Request ```bash curl --location --request GET 'https://api.piloterr.com/v2/jamesedition/search' \ --header 'Content-Type: application/json' \ --header 'x-api-key: YOUR_API_KEY' ``` ## Example Response ### Villa search, Lake Starnberg project ```json { "results": [ { "id": "17793477", "url": "https://www.jamesedition.com/real_estate/munich-germany/alpine-panorama-above-lake-starnberg-new-build-project-near-munich-17793477", "city": "Munich", "image": "https://img.jamesedition.com/listing_images/2026/05/07/09/16/45/419dac60-8b4b-4032-ac51-9765ab7d3418/je/507x312xc.jpg", "price": 670000, "title": "Alpine Panorama above Lake Starnberg – New-Build Project near Munich", "badges": [ "Directly from developer", "Video", "Promoted" ], "region": "Bavaria", "address": "Munich, Bavaria, Germany", "country": "Germany", "area_sqm": 43, "bedrooms": 1, "category": "Apartment", "currency": "EUR", "latitude": 48.1351253, "promoted": true, "bathrooms": 1, "longitude": 11.5819806, "price_eur": 670000, "price_usd": 750540, "office_url": "https://www.jamesedition.com/offices/real_estate/c7-gruppe-505101", "area_display": "43 sqm", "country_code": "DE", "price_display": "€670,000" } ], "pagination": { "next": "https://www.jamesedition.com/real_estate?q=villa&page=2", "page": 1, "per_page": 31, "total_pages": null, "total_results": null } } ``` ## Documentation ## Overview Search luxury homes on JamesEdition. A keyword such as `villa` calls `/real_estate?q=villa`. You can also send a results URL under `/real_estate`, for example `https://www.jamesedition.com/real_estate/france`. The response is `{ results, pagination }`. `price` is the amount printed on the card, and `price_display` is that label, such as `€670,000`. When the card says `Price on request`, `price` is null. `price_usd` and `price_eur` are the card's alternate amounts and can differ from `price`. ## Quickstart ``` GET https://api.piloterr.com/v2/jamesedition/search?query=villa GET https://api.piloterr.com/v2/jamesedition/search?query=villa&page=2 GET https://api.piloterr.com/v2/jamesedition/search?query=https://www.jamesedition.com/real_estate/france ``` Pass `results[].url` to `/v2/jamesedition/property`. The listing id matches `results[].id`. ## Parameters | Parameter | Required | Example | |---|---|---| | `query` | yes | `villa` | | `page` | no | `2` | `query` is a keyword or a jamesedition.com URL whose path starts with `/real_estate` and is not a single listing. A listing URL is rejected here. `page` starts at 1. Omit it for the first page. A `page` already present in a results URL is kept when you omit `page` or pass `1`. A value of `2` or higher overrides it. ## Response fields | Field | Type | Meaning | |---|---|---| | `results[].id` | string | Listing id | | `results[].url` | string | Listing URL | | `results[].title` | string or null | Card title | | `results[].price` | number or null | Printed amount. Null for `Price on request` | | `results[].price_display` | string or null | Printed label | | `results[].currency` | string or null | Currency of the printed label, such as `EUR` | | `results[].price_usd` | number or null | USD amount stored on the card | | `results[].price_eur` | number or null | EUR amount stored on the card | | `results[].city` | string or null | City | | `results[].region` | string or null | Region | | `results[].country` | string or null | Country | | `results[].country_code` | string or null | Country code, such as `DE` | | `results[].address` | string or null | Address from the card | | `results[].category` | string or null | Type, such as `Apartment` | | `results[].bedrooms` | integer or null | Beds printed on the card | | `results[].bathrooms` | integer or null | Baths printed on the card | | `results[].area_sqm` | number or null | Interior size in square meters | | `results[].area_display` | string or null | Size label, such as `43 sqm` | | `results[].latitude` | number or null | Latitude | | `results[].longitude` | number or null | Longitude | | `results[].image` | string or null | Card image | | `results[].badges` | array of strings or null | Badges such as `Promoted` | | `results[].promoted` | boolean | True when the card is promoted | | `results[].office_url` | string or null | Agency URL | | `pagination.page` | integer | Page you asked for | | `pagination.per_page` | integer | Number of cards on this page | | `pagination.total_results` | null | JamesEdition does not print a total on this page | | `pagination.total_pages` | null | Not printed | | `pagination.next` | string or null | Next page URL, or null when no next link is present | ## Pagination `page` starts at 1. Ids are unique on a page. Page 2 of `villa` returns `pagination.page` 2 and a `next` URL for page 3. `next` is null only when the page has no following link. `total_results` and `total_pages` stay null. The listing page can print a size that differs slightly from the card, because each page shows its own figure. ## Use cases - A buying agent searches `villa` and drops cards whose `price_display` is `Price on request`. - A developer compares `price_eur` and `price_usd` on promoted listings near Munich. - A relocation desk opens `https://www.jamesedition.com/real_estate/france` and walks `pagination.next`. ## Error codes | Code | Meaning | |---|---| | `400` | Empty query, a host other than jamesedition.com, or a listing URL sent to search | | `401` | Missing API key | | `404` | The page had no listing cards | | `500` | The fetch failed | ## Related endpoints [JamesEdition Property](https://www.piloterr.com/library/jamesedition-property)