Urbania APIurbania.pe ↗
Search Peru real estate listings, get location suggestions, and retrieve full property details including prices, features, and images via the Urbania.pe API.
What is the Urbania API?
The Urbania.pe API exposes 3 endpoints for accessing Peru's real estate market: search listings with price and area filters, resolve location IDs for districts like Miraflores or San Isidro, and retrieve full property detail records containing up to 10 structured response fields including amenities, coordinates, images, and multi-currency pricing. The get_listing_detail endpoint returns everything needed to display a complete property profile.
curl -X GET 'https://api.parse.bot/scraper/674ae4c8-a300-4438-80a7-ef1b86db7513/get_location_suggestions?limit=5&query=Lima' \ -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 urbania-pe-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.
from parse_apis.urbania_pe_api import Urbania, Sort, PropertyType, OperationType, Currency
urbania = Urbania()
# Search for locations matching "Miraflores"
for location in urbania.locations.search(query="Miraflores"):
print(location.id, location.name, location.label_suggest)
# Construct a known location and search its listings
miraflores = urbania.location(id="V1-D-51119497")
for listing in miraflores.listings.search(
sort=Sort.PRICE_ASC,
property_type=PropertyType.DEPARTAMENTO,
operation_type=OperationType.ALQUILER,
currency_id=Currency.SOLES,
bedrooms_min=2,
):
print(listing.title, listing.address)
for price in listing.prices:
print(price.currency, price.amount, price.formatted)
# Get full details from a summary
detail = listing.details()
print(detail.title, detail.publication_date, detail.amenities)
Search for location suggestions by name. Returns matching locations with their IDs and labels. Use the returned location_id in search_listings to scope results geographically. Each result includes a hierarchical label (district, city, department).
| Param | Type | Description |
|---|---|---|
| limit | integer | Max number of suggestions to return. |
| queryrequired | string | The location name to search for (e.g., 'Lima', 'Miraflores', 'San Isidro'). |
{
"type": "object",
"fields": {
"items": "array of location suggestion objects with id, name, label, labelSuggest, and tokens"
},
"sample": {
"data": {
"items": [
{
"id": "V1-D-51119497",
"name": "Miraflores",
"label": "barrio",
"tokens": [
"lima",
"miraflores"
],
"labelSuggest": "Miraflores, Lima, Lima"
}
]
},
"status": "success"
}
}About the Urbania API
What the API covers
The Urbania.pe API gives programmatic access to property listings on urbania.pe, one of Peru's primary real estate portals. It covers three operations: resolving location names to IDs, searching listings with filters, and fetching full detail records for individual properties. Data spans residential and commercial listings across Peru's districts, cities, and departments.
Location resolution and search
get_location_suggestions accepts a query string (e.g. 'Lima', 'Miraflores') and returns matching location objects including id, name, label, labelSuggest, and tokens. The id from this response feeds directly into search_listings to scope results geographically. search_listings supports filters for price_min, price_max, area_min, area_max, currency_id, and keyword query. Results are paginated; the response includes page, total_pages, and a formatted total count alongside an items array of listing summaries.
Listing detail fields
get_listing_detail accepts a listing_id obtained from search_listings and returns a complete record: title, url, address, expenses, images (array of URLs), prices (array with operation, currency, amount, and formatted per price entry), a features object covering total_area, covered_area, bedrooms, bathrooms, parking, and antiquity, a location object with district, city, and coordinates, and an amenities array of string descriptors.
Pagination and sorting
search_listings paginates via the page integer parameter. The total_pages field in each response indicates how many pages exist for a given query. An optional sort parameter controls result ordering. There is no cursor-based pagination; all navigation is by page number.
The Urbania API is a managed, monitored endpoint for urbania.pe — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when urbania.pe 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 urbania.pe 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?+
- Aggregate Lima property listings by district using location IDs from get_location_suggestions
- Build a price-per-square-meter calculator using area and price fields from search_listings results
- Sync a property database nightly by paginating through all pages of search_listings
- Display full property profiles including amenities, images, and coordinates from get_listing_detail
- Compare sale vs. rental prices for the same property using the prices array in get_listing_detail
- Filter properties by covered_area and bedroom count for a buyer-matching application
- Geocode property locations using the coordinates returned in the location object
| 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.