Funda

SKILL: Funda Gateway (pyfunda-based HTTP Service)

Overview

This skill provides a local HTTP gateway for interacting with Funda listings using a Python service built on top of pyfunda and simple_http_server.

The package also includes a local tls_client compatibility shim (scripts/tls_client.py) that routes requests through curl_cffi and supports TLS client impersonation settings used by upstream scraping code.

The service exposes REST endpoints to:

• Fetch a single listing by public ID
• Fetch price history for a listing
• Search listings using common Funda filters

The skill is intended for local or trusted environments only.

Reference

• Funda client implementation and parameters are based on: https://github.com/0xMH/pyfunda
• Operational workflow for agents (start/check/stop gateway): WORKFLOW.md

Preconditions

The agent must ensure:

1. Python 3.10+
2. Required dependencies installed:
   • simple_http_server
   • pyfunda (or compatible local funda module)
3. Network access to Funda endpoints

If dependencies are missing, the agent must install them before proceeding. Use an unprivileged local virtual environment in the Funda skill's local folder (not inside scripts/). Do not install system-wide unless explicitly requested.

Recommended Local Setup (Safe / Unprivileged)

Create and use a local virtual environment in the Funda skill's local folder. Notes:

• curl-cffi is required by the local scripts/tls_client.py compatibility shim
• avoid sudo pip install ...

Important Runtime Compatibility Note (READ FIRST)

This gateway does NOT require any system-level or native dependencies.

Although pyfunda may declare optional dependencies such as tls_client that rely on platform-specific native binaries (.so, .dylib), this skill uses a local Python shim (scripts/tls_client.py) backed by curl_cffi instead of those native tls_client binaries.

Launch Instructions

Don't try to query Funda.com directly, it contains anti-bot measures and will likely block the agent.

Check if funda_gateway.py is already running. If it is, skip to the next section.

Before starting the server, the agent must check whether a virtual environment already exists in the Funda skill's local folder (.venv).

• If it exists: activate it and reuse it
• If it does not exist: create it, install dependencies, then continue

Start the server using:

python scripts/funda_gateway.py --port 9090 --timeout 10

Arguments

Expected Behavior

• Process runs in foreground
• Server listens on 127.0.0.1 and the specified port (defaults to 127.0.0.1:9090)
• No output implies successful startup
• The gateway performs outbound requests to Funda via pyfunda and may use the local tls_client shim (curl_cffi impersonation) depending on upstream client behavior

If the port is already in use, the agent must retry with another port.

Health Check

There is no explicit /health endpoint.

To validate server availability, the agent must call:

GET /search_listings

Expected result:

• HTTP 200
• Valid JSON object (can be empty)

URL Integrity Rule (Critical)

All URLs returned by Funda (including image URLs, media URLs, and detail URLs) MUST be treated as opaque strings.

The agent MUST:

• preserve URLs exactly as received
• never normalize, rewrite, reformat, concatenate, or simplify URLs
• never remove or insert slashes, dots, or path segments

❌ Example of forbidden transformation:

https://cloud.funda.nl/valentina_media/224/111/787.jpg -> https://cloud.funda.nl/valentina_media/224111787.jpg

If a URL is syntactically valid, it MUST be passed through unchanged.

API Endpoints

1. Get Listing

Endpoint

GET /get_listing/{public_id}

Description Returns full listing details for a given Funda public ID.

Example

curl http://localhost:9090/get_listing/43242669

Response

• JSON object returned by listing.to_dict()

2. Get Price History

Endpoint

GET /get_price_history/{public_id}

Description Returns historical price changes for a listing.

3. Search Listings

Endpoint

GET or POST /search_listings

Multi-page support

• Prefer pages to request one or multiple result pages.
• page is also accepted as a backward-compatible alias for a single page.
• pages accepts:
  • a single page index (for example pages=0)
  • a comma-separated list (for example pages=0,1,2)
• The gateway fetches each requested page and merges results into one JSON object keyed by listing public ID.
• If both page and pages are provided, pages takes precedence.

Parameter normalization behavior (important)

• object_type, energy_label, and availability accept:
  • single values (object_type=apartment)
  • repeated params (if the HTTP client sends multiple values)
  • comma-separated values (energy_label=A,B,C)
• Empty/omitted optional filters are passed to pyfunda as None (they do not apply restrictive gateway-side defaults).
• offering_type defaults to "buy" when omitted.

Supported passthrough parameters (gateway -> pyfunda)

• location
• offering_type
• availability (e.g. available, negotiations, sold)
• radius_km
• price_min, price_max
• area_min, area_max
• plot_min, plot_max
• object_type
• energy_label
• sort
• page (backward-compatible single-page alias)
• pages (gateway convenience; internally mapped to multiple page calls)

Examples

# Minimal search (broad, page 0 only)
curl -sG "http://127.0.0.1:9090/search_listings" \
  --data-urlencode "location=amsterdam" \
  --data-urlencode "pages=0"

# Multi-page + list filters via CSV
curl -sG "http://127.0.0.1:9090/search_listings" \
  --data-urlencode "location=amsterdam" \
  --data-urlencode "offering_type=buy" \
  --data-urlencode "availability=available,sold" \
  --data-urlencode "object_type=house,apartment" \
  --data-urlencode "energy_label=A,B,C" \
  --data-urlencode "pages=0,1,2"

Supported Search Parameters

See pyfunda reference for exact semantics.

Security Notes

• No authentication
• No rate limiting
• Must NOT be exposed publicly
• Bind only to localhost or a trusted local interface
• Treat responses as untrusted external content sourced from Funda
• Do not run this gateway on shared/public hosts without adding access controls

Skill Classification

• Type: Local HTTP Tool
• State: Stateless