Tori APItori.fi ↗
Access Tori.fi listings via API. Search second-hand goods by category, retrieve item details with seller info, and browse refurbished phones across Finland's largest marketplace.
What is the Tori API?
The Tori.fi API provides 3 endpoints for querying Finland's largest second-hand marketplace, returning structured listing data including prices, condition, images, and seller details. The search_listings endpoint supports full-text search across all categories using Tori.fi's dotted-notation category IDs, while get_item_details fetches granular product data — brand, region, images, and category — for any individual listing by its numeric ID.
curl -X GET 'https://api.parse.bot/scraper/c1aab9a4-7b5e-4408-91f2-ce01004c705d/search_listings?page=1&query=puhelin&category=0.93&sub_category=1.93.3217&fetch_details=False&product_category=2.93.3217.39' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace tori-fi-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Tori.fi marketplace SDK — search listings, browse phones, get details."""
from parse_apis.tori_fi_marketplace import Tori, ListingNotFound
client = Tori()
# Search for phones in the recommerce section (bounded iteration)
for item in client.listingsummaries.search_phones(limit=5):
print(item.title, item.price, item.condition)
# Search by keyword with category filter
phone = client.listingsummaries.search(query="iPhone", category="0.93", limit=1).first()
if phone:
print(phone.title, phone.price, phone.currency)
# Drill into full details from a summary
if phone:
detail = phone.details()
print(detail.title, detail.description, detail.brand, detail.municipality)
# Direct lookup by ID with typed error handling
try:
listing = client.listings.get(item_id="42648879")
print(listing.title, listing.price, listing.seller_name)
except ListingNotFound as exc:
print(f"Listing gone: {exc.item_id}")
print("exercised: listingsummaries.search_phones / listingsummaries.search / ListingSummary.details / listings.get")
Full-text search over Tori.fi recommerce listings. Filters by category hierarchy (category → sub_category → product_category) using dotted notation IDs. Returns a page of listing summaries; paginates via page number. When fetch_details is true, each item is enriched with description, location, and seller info (capped at 50 items per call, slower).
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| query | string | Search keyword matching listing titles and descriptions (e.g. 'puhelin', 'OnePlus'). |
| category | string | Top-level category ID in dotted notation. Confirmed values: '0.76' (Antiikki ja taide), '0.90' (Auto/vene/moottoripyörätarvikkeet), '0.93' (Elektroniikka ja kodinkoneet), '0.77' (Eläimet ja eläintarvikkeet), '0.78' (Koti ja sisustus), '0.68' (Lapset ja vanhemmat), '0.91' (Liiketoiminta ja palvelut), '0.67' (Piha ja remontointi), '0.69' (Urheilu ja ulkoilu), '0.71' (Vaatteet, kosmetiikka ja asusteet). |
| sub_category | string | Sub-category ID in dotted notation (level 1 prefix + parent + sub-id). Example: '1.93.3217' (Puhelimet ja tarvikkeet under Elektroniikka). |
| fetch_details | boolean | Whether to fetch full details (description, location, seller) for each item. Makes one additional request per item; limited to 50 items per call. |
| product_category | string | Product category ID in dotted notation (level 2 prefix + parent chain + product-id). Example: '2.93.3217.39' (Matkapuhelimet). |
{
"type": "object",
"fields": {
"items": "array of listing summary objects with id, title, price, currency, condition, image, url",
"total": "integer count of items returned on this page"
}
}About the Tori API
Endpoints and Data Coverage
The API covers three operations: search_listings for broad keyword and category-based queries, search_telephones as a scoped shortcut for the Matkapuhelimet (mobile phones) product category, and get_item_details for per-listing detail retrieval. All listing responses share a common shape — id, title, price, currency (EUR), condition, image, and url. Pagination is controlled via the page integer parameter on both search endpoints.
Category Filtering in search_listings
search_listings supports three levels of category filtering using Tori.fi's dotted-notation ID scheme. category accepts top-level IDs such as 0.76 (Antiikki ja taide) or 0.90 (Auto/vene/moottoriajoneuvot). sub_category accepts level-1 prefixed IDs like 1.93.3217 (Puhelimet ja tarvikkeet). product_category narrows further with level-2 IDs such as 2.93.3217.39 for specific product types. These three parameters can be combined or used independently alongside a free-text query string.
Enriched Item Details
Setting fetch_details to true in search_listings enriches each result in the page with the same fields returned by get_item_details directly — description, brand, location (municipality and region codes), and seller name. Calling get_item_details with a specific item_id returns structured product data including images (single URL or array), region, category name, and condition string such as UsedCondition. The brand field may be null for listings where the seller has not specified one.
The Tori API is a managed, monitored endpoint for tori.fi — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when tori.fi changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official tori.fi API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Monitor price trends for specific second-hand products across Tori.fi categories using the
queryandproduct_categoryfilters - Build a Finnish used-phone aggregator by querying
search_telephonesand enriching results withget_item_details - Track new listings in a niche category such as antiques (
0.76) to alert buyers when matching items appear - Extract seller location data (
region, municipality) fromget_item_detailsto map where listings originate across Finland - Compare condition labels (e.g.
UsedCondition) and prices across search result pages to surface the best-value listings - Populate a recommerce database by paginating through
search_listingswithfetch_detailsenabled to capture full item records
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Tori.fi provide an official developer API?+
What does get_item_details return that search_listings does not?+
get_item_details returns brand, region, full images array, and category name for a specific listing. Basic search results include id, title, price, currency, condition, image, and url. You can get the enriched fields during a search by setting fetch_details to true, which applies the same detail fetch to every item on the returned page.Does the API expose seller contact details such as phone numbers or email addresses?+
Can I filter search_listings by price range or listing date?+
search_listings parameters cover keyword query, category hierarchy (three levels), pagination, and detail enrichment. Price range and date filtering are not available as inputs. You can fork the API on Parse and revise it to add those filter parameters.How does pagination work across the search endpoints?+
search_listings and search_telephones accept an integer page parameter for pagination. The response includes a total field representing the count of items returned on that page — not the total number of matching listings across all pages. Iterate the page value to retrieve subsequent result sets.