urbania.pe APIurbania.pe ↗
Search Peru real estate listings, get location suggestions, and retrieve full property details including price, features, and images via the Urbania API.
curl -X GET 'https://api.parse.bot/scraper/674ae4c8-a300-4438-80a7-ef1b86db7513/get_location_suggestions?limit=10&query=Lima' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for location suggestions by name to find the correct location_id for use in search_listings. Returns an array of matching locations with their IDs and labels.
| 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": {
"data": "array of location suggestion objects, each with id, name, label, labelSuggest, and tokens",
"status": "string ('success')"
},
"sample": {
"data": [
{
"id": "V1-B-4368",
"name": "Lima",
"label": "provincia",
"tokens": [
"lima"
],
"labelSuggest": "Lima"
},
{
"id": "V1-D-51119497",
"name": "Miraflores",
"label": "barrio",
"tokens": [
"lima",
"miraflores"
],
"labelSuggest": "Miraflores, Lima, Lima"
}
],
"status": "success"
}
}About the urbania.pe API
The Urbania API provides access to Peru's Urbania.pe real estate platform through 3 endpoints covering location lookup, listing search, and full property detail retrieval. Use search_listings to filter properties by price range, area, currency, and sort order, then call get_listing_detail with a listing ID to fetch complete data including amenities, advertiser info, images, and publication date.
Endpoints Overview
The API exposes three endpoints. get_location_suggestions accepts a query string (e.g., 'Miraflores' or 'San Isidro') and returns an array of location objects, each carrying an id, name, label, labelSuggest, and tokens field. The returned id is what you pass as a location filter in search_listings. An optional limit parameter caps the number of results.
Searching Listings
search_listings is a POST endpoint that accepts a range of filters: price_min and price_max (paired with currency_id — 1 for Soles, 2 for USD), area_min and area_max in square meters, a free-text query, and a sort value of relevance, price_asc, price_desc, or newest. Results are paginated; the response data object includes total (formatted string), page, total_pages, and an items array of listing summaries with IDs you can pass downstream.
Listing Detail
get_listing_detail takes a single listing_id string and returns a detailed object covering id, title, url, property_type, address, location, features, description, advertiser, and images. This is the endpoint to use when you need the full picture on a specific property: room counts, surface area breakdowns, and contact information for the advertiser.
Coverage Notes
All listings are sourced from Urbania.pe, which focuses on the Peruvian market. Currency filtering supports Soles and USD. Pagination is available through the page parameter on search_listings, allowing iteration across large result sets.
- Build a property price tracker that monitors Soles vs. USD listing prices over time using
search_listingswithcurrency_idfilters. - Populate a neighborhood comparison tool by querying
get_location_suggestionsfor Lima districts and aggregating listing counts and median prices. - Feed a real estate alert service that pages through
search_listingsresults sorted bynewestto catch new listings as they appear. - Generate property detail pages for a Peru-focused real estate aggregator using
get_listing_detailfor full descriptions, features, and images. - Analyze supply of properties in specific size bands by filtering
area_minandarea_maxacross multiple Lima locations. - Display advertiser contact information and listing URLs in a CRM by pulling
advertiserandurlfields fromget_listing_detail.
| 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 | 250 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 Urbania.pe have an official developer API?+
What location data does `get_location_suggestions` return, and how is it used with `search_listings`?+
get_location_suggestions returns an array of objects each containing id, name, label, labelSuggest, and tokens for each matching place name. The id field from these results is the value you supply as a location filter when calling search_listings, linking the two endpoints together.Does `search_listings` support filtering by property type (e.g., apartment vs. house)?+
search_listings inputs cover price range, area, currency, keyword query, sort order, and page. A dedicated property type filter parameter is not currently exposed. You can fork the API on Parse and revise it to add a property type filter endpoint.Does `get_listing_detail` return historical price data or price change history for a property?+
get_listing_detail returns the current listing price and features at the time of the request — fields like title, description, features, advertiser, and images. Historical pricing is not part of the response. You can fork the API on Parse and revise it to add a price history endpoint if Urbania exposes that data.How does pagination work in `search_listings`?+
data object includes page (current page integer), total_pages (total number of pages), and total (a formatted string of total results). Pass incrementing page values in successive requests to iterate through all results. There is no cursor-based pagination — only numeric page offsets.