# RED Atlas API Documentation

Everything you need to build with RED Atlas API

English-only full documentation export for LLM ingestion.
Docs home: /en/docs
Index file: /llms.txt
API base URL: https://apiv3.atlas.red/external-api/v1

# Common Filters
URL: /en/docs?section=filtering

These parameters apply across list endpoints.
- page: Page number. Default: 1
- limit: Results per page. Default: 25, max: 100
- sort: Sort by field. Format: field:asc or field:desc. Default: id:desc
- fields: Comma-separated list of fields to return. Omit for all fields.
- filter exact: Exact match filter on any field
- filter gte: Greater than or equal
- filter lte: Less than or equal
- filter gt: Greater than
- filter lt: Less than
- filter neq: Not equal
- filter like: Case-insensitive substring match (ILIKE)
- filter in: IN list. Values comma-separated, case-sensitive, and matched exactly. E.g. filter[status.in]=FOR_SALE,UNDER_CONTRACT_SALE

## Getting Started

# Introduction
URL: /en/docs?section=introduction

RED Atlas API provides programmatic access to the most comprehensive real estate dataset in Latin America and the Caribbean. Our REST API lets you query properties, listings, transactions, permits, and more across 2 active markets (Colombia and Puerto Rico), with consistent schemas and low latency.

## Base URL

## Key Features
- feature entities: 10+ entity types (properties, listings, transactions, permits, and more)
- feature filters: Consistent filter, sort, and pagination API across all entities
- feature fields: Field selection — request only the fields you need
- feature premium: Premium fields: AI-generated descriptions, AVM pricing, JSON enrichment
- feature reports: White-label report generation with AVM valuation
- feature rate limits: Rate limit info included in every response

# Quick Start
URL: /en/docs?section=quick-start

Get up and running in under 2 minutes.

## 1. Get your API Key
- step1 description before: Sign in to the dashboard and go to
- step1 api keys label: API Keys
- step1 description after: → Create Key. Copy the full key — it is shown only once.

## 2. Make your first request

## 3. Read the response

# Authentication
URL: /en/docs?section=authentication

Every request to the Data API and Report API must include your API key as a Bearer token.

## Bearer Token

## Key prefix
- key prefix description: Production key. Full access to your plan features and real data.

## Security notes
- security note1: Never expose API keys in client-side code or public repositories.
- security note2: Rotate keys periodically from the dashboard. Old key is immediately revoked.
- security note3: Use separate keys per environment (production vs staging).
- security note4 before: Restrict keys to specific markets using
- security note4 after: when creating.

# Rate Limits & Errors
URL: /en/docs?section=rate-limits

Two independent limits apply. A per-minute request throttle per API key (429 when exceeded), and a monthly budget reported in the `rateLimit` object of every metered response body. There are no X-RateLimit-* response headers — read the body.

## Rate Limits by Plan
- plan enterprise: Unlimited calls

## Remaining Budget (rateLimit)

## Error Format
- error format description: All errors return a consistent JSON shape:

## HTTP Status Codes
- status 200: Request successful
- status 201: Resource created (reports)
- status 400: Invalid filter field, sort, or body parameter
- status 401: Missing or invalid API key
- status 403: Plan does not include this feature or market
- status 404: Resource or entity not found
- status 429: Too many requests — the per-minute throttle. Back off and retry; the monthly budget is reported in the response body instead.
- status 500: Internal error. Retry with exponential backoff
- body note: `unit` is credits on credit-metered plans and calls on call-metered ones. `limit` is everything spendable this period (`subscriptionLimit` + `topupCredits`), so `remaining` is never greater than it, and `remaining` already accounts for the request that returned it. `reset` is the Unix second at which the period rolls over. The whole object is absent (null) on unlimited plans.

# Credit Costs
URL: /en/docs?section=credit-costs

A call costs the entity base rate per record returned, plus the rate of any premium, indicator or enrichment field you explicitly ask for. Standard fields add nothing.

## How it works
- bullet per field: Every call deducts (base rate for the entity + the rate of each premium / indicator / enrichment field you requested) × the number of records returned. Standard fields are covered by the base rate.
- bullet projection: `fields` shrinks the payload, not the bill — dropping standard fields changes nothing. It only lowers cost when the field you drop is a premium / indicator / enrichment one. Omit `fields` entirely and you pay the base rate alone.
- bullet flat call: Aggregated endpoints (stats, trend, delta, top-by, pivot, points, market-report), search and reports are billed per CALL at a flat rate, not per record. The exact amount is echoed in `meta.creditCost` on every response.
- bullet min tier: No field is restricted by plan today: any active key may request any field and is billed the credit cost below. Your monthly credit allowance is what differs between plans.
- bullet premium: Premium fields (AI descriptions, AVM valuation, enrichment) typically cost more than standard fields.
- bullet contact enrichment: Contact enrichment (POST /v1/enrichment/contacts) is billed the contacts_enriched price only when it unlocks someone your organization did not already hold — a no-match or a repeat lookup costs 0. Contact requests (POST /v1/contacts/requests) are billed the contacts price per newly unlocked contact.

## Simulate your usage
- cta description: See every field's credit cost and estimate your monthly consumption on the public credits page.
- cta link: Open the calculator

## Data API

# Data API Overview
URL: /en/docs?section=overview

The Data API gives you direct access to real estate records across all covered markets. Every endpoint follows the same pattern and accepts the same filter, sort, and pagination parameters.

## URL Pattern

## Filter Operators
- filter operators description: All list endpoints support the same filter syntax. The field name can be any column name of that entity.

## Response Envelope

# Markets & Coverage
URL: /en/docs?section=markets

Use the market code in the URL path to specify which country's data to query.
- pri description: properties, listings, parcels, transactions, permits, tenants, documents, taxes, buildings, shortTermRentals
- col description: properties, listings, parcels, transactions, permits, tenants, documents, buildings, taxes, shortTermRentals
- arg type: Argentina — coming soon
- arg description: properties, listings, parcels, transactions, permits, tenants
- esp type: Spain — coming soon
- esp description: properties, listings, transactions
- are type: UAE — coming soon
- are description: properties, listings, transactions

## Check available entities

# Properties
URL: /en/docs?section=properties

Core property records linked to government cadastral data. Each property has a unique government ID, area, address, and links to parcels, listings, and transactions.
- available in: Available in:

## Query Parameters

## Response Fields

## Example Request

## Example Response
- filter govtId: Filter by government cadastral ID
- filter totalArea gte: Minimum total area in m²
- filter totalArea lte: Maximum total area in m²
- filter yearBuilt gte: Minimum year built (COL)
- filter sectorId: Filter by sector ID
- filter subsectorId: Filter by subsector ID
- filter uso: Land use classification e.g. RESIDENCIAL (COL)
- filter unitType: Property unit type e.g. Particular, Unit
- filter cityId: Filter by city
- field id: Unique property identifier
- field govtId: Official government cadastral ID
- field address: Full formatted address string
- field addressJSON: Parsed address components (mainStreet, secundaryStreet, unitNumber, unitType, joinedAddress)
- field totalArea: Total property area in m²
- field sourceId: Internal source data identifier
- field sectorId: Sector (neighborhood) identifier
- field subsectorId: Subsector identifier
- field microsectorId: Microsector identifier
- field unitType: Property unit type (e.g. Particular, Apartment, Commercial)
- field geometry: Point coordinates of the property
- field parcelId: Linked parcel record
- field uso: Land use classification (e.g. RESIDENCIAL, COMERCIAL)
- field matriculaInmobiliaria: Real estate registry folio number
- field yearBuilt: Year of construction
- field usoVivienda: Housing use subcategory
- field destinoEconomico: Economic destination type
- field uniqueListingsCount: Number of unique listings linked to this property
- field uniqueTransactionsCount: Number of unique transactions linked to this property
- field rooms: Number of rooms
- field toilets: Number of bathrooms
- field parkingSpaces: Number of parking spaces
- field neighborhoodId: Neighborhood reference
- field cityId: City reference
- field taxesCount: Number of linked tax records
- field listings: Nested listing records linked to this property
- field parcel: Nested parcel record (with geometry, centroid, neighborhood)
- field transactions: Nested transaction records
- field taxes: Nested tax records

# Parcels
URL: /en/docs?section=parcels

Land parcel records from cadastral registries. Parcels contain plot-level data including land area, geometry, government IDs, and zoning classifications.

## Query Parameters

## Response Fields

## Example Request

## Example Response
- filter govtId: Cadastral parcel ID
- filter landArea gte: Minimum land area in m²
- filter landArea lte: Maximum land area in m²
- filter totalArea gte: Minimum total constructed area in m²
- filter cityId: Filter by city
- filter stratum: Stratum 1–6 (COL)
- filter sectorId: Filter by sector
- filter neighborhoodId: Filter by neighborhood
- filter buildingId: Filter parcels in a building (COL)
- field id: Unique parcel identifier
- field govtId: Government cadastral parcel ID
- field name: Parcel name or reference
- field description: Parcel description
- field landArea: Land area in m²
- field totalArea: Total constructed area in m²
- field address: Street address
- field photos: Photo URLs
- field score: Atlas data quality score 0–100
- field stratum: Socioeconomic stratum 1–6
- field chip: Unique cadastral chip code
- field cityId: City reference
- field sectorId: Sector reference
- field subsectorId: Subsector reference
- field microsectorId: Microsector reference
- field neighborhoodId: Neighborhood reference
- field buildingId: Building reference (if part of a building)
- field regionId: Region reference
- field uniqueListingsCount: Count of unique listings on this parcel
- field uniqueTransactionsCount: Count of unique transactions on this parcel
- field permitsCount: Count of linked building permits
- field tenantsCount: Count of linked tenant/business records
- field propertiesCount: Count of properties on this parcel
- field documentsCount: Count of linked documents
- field createdAt: Record creation timestamp
- field updatedAt: Last update timestamp
- field geometry: Polygon boundary of the parcel
- field centroid: Centroid point of the parcel
- field listings: Nested listing records on this parcel
- field properties: Nested property records on this parcel
- field tenants: Nested tenant/business records
- field documents: Nested document records
- field sector: Nested sector info

# Parcel Contacts
URL: /en/docs?section=parcel-contacts

The people tied to a parcel — brokers, permit professionals, deed parties — with their role and the record each one came from, paginated and sorted by creation date (newest first). Phone numbers and emails are never listed here: request them with POST /v1/contacts/requests.
- note: Free (discovery). The plan tier on the contacts price row still applies. Available for COL and PRI parcels only.
- data note: We return the best contact data we have for each parcel. Coverage varies: a parcel may have no contacts, and an individual contact may be missing some fields (e.g. phone, email, or name). Fields that are unavailable are omitted or returned as null — design your integration to handle partial records.

## Query Parameters

## Response Fields

## Example Request

## Example Response
- field id: Unique contact identifier
- field createdAt: When the contact record was added
- field typePerson: Role of the contact (e.g. Broker, Owner)
- field fullName: Contact full name (may be null)
- field mail: Always empty in this listing — read the details from the contact repository
- field phone: Always empty in this listing — read the details from the contact repository
- field profession: Contact profession or occupation (may be null)
- field address: Contact address (may be null)
- field source: Provenance of the contact record (e.g. Listing)
- field genericListingId: Linked listing, if the contact came from a listing
- field permitId: Linked permit, if the contact came from a permit
- field transactionId: Linked transaction, if the contact came from a transaction
- field hasMail: Whether RED Atlas holds an email for this person — something a contact request would unlock
- field hasPhone: Whether RED Atlas holds a phone number for this person
- field unlock: Your organization's state for this person: { state: locked | processing | unlocked, contactId } — contactId is the repository id once requested
- field personKey: Groups one person's records across sources (the same broker on many listings)

# Contact Enrichment
URL: /en/docs?section=contact-enrichment

Skip-trace lookup for a person or an address. The people found are filed in your organization's contact repository and this response is a receipt: names and match flags, never phone numbers, emails or addresses — read those from GET /v1/contacts/{contactId}. Results are persisted: a repeat lookup of the same subject is served from the RED Atlas store — data.servedFrom tells you which one you got ("store" or "provider").
- note: Charged the contacts_enriched price (see Credit Costs) only when the lookup unlocks someone your organization did not already hold. A no-match, a provider failure or a repeat of a lookup you already paid for costs 0 credits; meta.creditCost echoes the amount actually charged.
- data note: Coverage is US / Puerto Rico only (the vendor is a US skip-trace provider). An individual contact may be missing some fields (e.g. name or email) — design your integration to handle partial records.

## Request Body
- request body note: All fields are optional strings, but at least one of address, phone, or lastName is required.
- field firstName: First name of the person to look up
- field lastName: Last name of the person to look up
- field address: Street address line, e.g. "67 CALLE DIAMANTE" (urbanization prefixes are normalized away)
- field city: City name
- field state: Two-letter state code, e.g. "PR"
- field zip: ZIP code
- field phone: Phone number, in any format
- field force: Bypass the store and force a fresh vendor fetch (charged like any hit)

## Response Fields
- field status: "hit" when contacts were found, "no_match" otherwise
- field provider: Vendor that resolved the lookup
- field servedFrom: "store" when served from the RED Atlas store, "provider" on a fresh vendor fetch
- field matchCount: Number of contacts returned
- field contacts: Who the lookup found (see the contacts[] fields below)
- field contact fullName: Contact full name (may be omitted)
- field extractedAt: When the data was last fetched from the provider (ISO datetime)

## Example Request

## Example Response
- field contact contactId: Repository id — read the phone numbers, emails and addresses from GET /v1/contacts/{contactId}
- field contact status: ready (unlocked by this lookup), already_unlocked (your organization had it), or unavailable (nothing to deliver)
- field contact addressMatch: true when this person is tied to the address searched; false for an association (a shared surname, an old phone)
- field contact matchesParcelOwner: true when the name matches the owner on the parcel roll (or the name you sent)
- field receipt: The contact request receipt (see Contact Requests); null on a no-match

# Contact Requests
URL: /en/docs?section=contact-requests

Contact requests are asynchronous. The API returns a receipt and charges credits at request time; phone and email are delivered to your RED Atlas repository (and by email to the requesting user), never in the API response. Poll the request URL, then read the contact from /v1/contacts/{contactId}. Requests for a contact your organization has already unlocked return already_unlocked and are free.
- note: Charged the contacts price (see Credit Costs) per contact your organization has not unlocked yet. Unlocks belong to the organization and never expire. At most 25 contacts per request.
- connector note: Through an AI connector (Claude, ChatGPT) the same request returns the same receipt, and the repository reads below are refused: assistant providers do not allow personal contact data in a tool result.

## Request contacts

## Request Body
- field market: pri or col (default pri)
- field contactIds: Row ids from Parcel Contacts (1 to 25)

## Receipt
- field status: requested (something new was unlocked), already_unlocked (nothing new, nothing charged) or unavailable (RED Atlas holds no phone or email for them)
- field requestId: The request id (ctr_…) — poll GET /v1/contacts/requests/{requestId}
- field contacts: One entry per person: { contactId, name, role, from, status }
- field repositoryUrl: Where the details are in RED Atlas (Repository › Contacts)
- field credits: { charged, perContact }

## Read the repository
- repository note: GET /v1/contacts lists the contacts your organization unlocked (search, market, typePerson, status, requestId, sort, page, limit); GET /v1/contacts/{contactId} returns one. Both carry phones, emails and addresses. PATCH /v1/contacts/{contactId} with { shared } keeps a contact private to the member who requested it; POST /v1/contacts/{contactId}/reverify re-reads one from its RED Atlas records for free.

## Example Request

## Example Response

# Listings
URL: /en/docs?section=listings

Active and historical real estate listings scraped and normalized from portals. Includes property type, rooms, areas, price and publisher information. Note there is no per-listing price history: the timestamps below are the entire listing timeline.

## Query Parameters

## Response Fields

## Example Request

## Example Response
- filter status: FOR_SALE | FOR_RENT | SOLD | RENTED | UNDER_CONTRACT_SALE | UNDER_CONTRACT_RENT | REMOVED_SALE | REMOVED_RENT | AUCTION | AUCTIONED
- filter active: Filter currently active listings
- filter is outlier: Exclude prices ingest flagged as scraped placeholders. Pass false before summing or averaging money.
- filter price gte: Minimum price (local currency)
- filter price lte: Maximum price
- filter builtArea gte: Minimum built area in m²
- filter builtArea lte: Maximum built area in m²
- filter rooms: Exact number of bedrooms
- filter rooms gte: Minimum bedrooms
- filter toilets gte: Minimum bathrooms
- filter propertyType: Property type e.g. APARTMENT, HOUSE, OFFICE (COL, PRI)
- filter stratum: Stratum 1–6 (COL)
- filter yearBuilt gte: Minimum year built
- filter daysOnMarket lte: Max days on market
- filter ageStatus: USED | NEW (COL)
- filter dataset: Ingest classification (duplicate, sublisting, parent, incomplete, outlier, train, test). Naming it lifts the default exclusion of duplicates.
- field genericListingId: Primary key for listings
- field uniqueListingId: Canonical id of the de-duplication cluster this row belongs to. Rows sharing it are the same property; the canonical row is the one whose genericListingId equals it.
- field listingCode: Source portal listing code
- field name: Listing title from the source portal
- field price: Listing price in local currency (COP for COL, USD for PRI)
- field builtArea: Built area in m²
- field exteriorBuiltArea: Exterior/balcony built area in m²
- field lotArea: Lot area in m²
- field pricePerBuiltSqm: Price per built m²
- field pricePerLotSqm: Price per lot m²
- field daysOnMarket: Days since first listed
- field url: Source listing URL
- field location: Listing location coordinates
- field status: FOR_SALE | FOR_RENT | SOLD | RENTED | UNDER_CONTRACT_SALE | UNDER_CONTRACT_RENT | REMOVED_SALE | REMOVED_RENT | AUCTION | AUCTIONED
- field active: Whether the listing is still live at the source. Ingest retires listings their source stopped showing, which also moves status to REMOVED_SALE/REMOVED_RENT, so read active together with status.
- field is outlier: true when ingest flagged the price as a scraped placeholder (e.g. a “call for price” listing indexed at 99,900,000). Those records are excluded from the excludingOutliers block on the stats endpoint.
- field dataset: Ingest classification, not the source portal (use sourceId for that): duplicate, sublisting, parent, incomplete, outlier, train, test. Rows classified duplicate or sublisting are excluded from results by default.
- field photos: First 5 photo URLs
- field allPhotos: All photo URLs
- field rooms: Number of bedrooms
- field toilets: Number of bathrooms
- field parkingSpaces: Number of parking spaces
- field floor: Floor number of the unit
- field stratum: Socioeconomic stratum 1–6
- field address: Formatted address
- field addressJSON: Parsed address components
- field descriptionText: Original listing description from portal
- field publisherName: Publisher/agent name
- field publisherType: Publisher category (owner, agency, developer)
- field brokerName: Listing brokerage name. Groupable via the aggregator (`groupBy=brokerName`) for brokerage market share; also filterable with the `like` operator.
- field brokerAgentNames: Individual agent / brokerage names attached to the listing, indexed as exact terms so they can be grouped (`groupBy=brokerAgentNames`) for an agent census. Contact phones and emails are never indexed.
- field brokersInfo: Broker/agent block per listing. Every leaf is searchable with dotted filter syntax: brokersInfo.broker_name, broker_company, broker_phones, broker_emails, broker_license (phones are stored with a "tel:" prefix, so use the like operator). Aggregating the phone/email leaves is not permitted — to count by agent use brokerAgentNames.
- field phones: Listing contact phone numbers. Searchable, including with the like operator.
- field emails: Listing contact emails. Searchable, including with the like operator.
- field yearBuilt: Year of construction
- field propertyType: Property type (APARTMENT, HOUSE, OFFICE, etc.)
- field score: Atlas data quality score 0–100
- field ageStatus: USED | NEW
- field ageGroup: Human-readable age bracket (e.g. Más de 20 años)
- field ageMin: Minimum estimated age in years
- field ageMax: Maximum estimated age in years
- field ageNumeric: Estimated numeric age in years
- field administrationFee: Monthly administration fee (COP)
- field isDuplex: Whether the unit is a duplex
- field isExterior: Whether the unit has exterior exposure
- field hasServiceRoom: Whether the unit has a service room
- field amenitiesCount: Number of listed amenities
- field hasVisitorParking: Whether the building has visitor parking
- field condition: Physical condition of the property
- field dealOpportunity: Atlas deal opportunity classification
- field estimatedSaleValue: AVM estimated sale value
- field estimatedMonthlyRentValue: AVM estimated monthly rent value
- field createdAt: Date when listing was first seen
- field updatedAt: When the record last changed or was re-confirmed.
- field deactivatedAt: Date listing was removed from portal
- field extractedAt: When the extraction step last processed this row. This is NOT a last-seen date — a listing re-confirmed daily whose details never change keeps an old extractedAt, so do not derive staleness from it.
- field parcel: Nested parcel record (id, buildingId, permits, tenants)
- field property: Nested property record linked to this listing

# Transactions
URL: /en/docs?section=transactions

Recorded real estate transactions from public registries. Includes deed prices, buyer/seller names, property areas, and transaction dates.

## Query Parameters

## Response Fields

## Example Request

## Example Response
- filter transactionType: Transaction type as recorded in the notarial registry (COL: e.g. Compraventa, Cancelación De Hipoteca…)
- filter transactionPrice gte: Minimum transaction price
- filter transactionPrice lte: Maximum transaction price
- filter transactionDate gte: Earliest date (ISO 8601: 2024-01-01)
- filter transactionDate lte: Latest date (ISO 8601)
- filter builtArea gte: Minimum built area in m²
- filter sectorId: Filter by sector
- filter parcelId: All transactions for a parcel
- filter NIR: Notarial instrument reference number (COL)
- field id: Unique transaction identifier
- field shortId: Short alphanumeric reference ID
- field transactionPrice: Recorded deed price in local currency (may be null if not disclosed)
- field builtArea: Built area in m²
- field pricePerBuiltSqm: Price per built m²
- field lotArea: Lot area in m²
- field pricePerLotSqm: Price per lot m²
- field transactionType: Transaction type as recorded in the notarial registry
- field buyerName: Buyer name from public registry
- field sellerName: Seller name from public registry
- field address: Property address at time of transaction
- field dataset: Source completeness tag (complete | incomplete)
- field transactionDate: Date and time of transaction
- field sourceId: Internal source identifier
- field sectorId: Sector reference
- field subsectorId: Subsector reference
- field microsectorId: Microsector reference
- field parcelId: Linked parcel
- field genericListingId: Linked listing (if matched)
- field masterTransactionId: Master transaction reference for grouped deeds
- field NIR: Notarial instrument reference number
- field createdAt: Record creation timestamp
- field updatedAt: Last update timestamp
- field scripturesJson: Deed extraction: structured fields read from the scanned deed and its registry presentation receipt. Present on part of the corpus — see coverage below.
- field deed deedNumber: Deed number as written in the deed itself.
- field deed typeCanonical: Normalised deed type (Compraventa, Hipoteca, Cancelación, Declaratoria de Herederos, Instancia). Exact-match filterable and groupable.
- field deed transactionDate: Date the deed was granted, which can differ from transactionDate (the registry date).
- field deed notary: Notary who granted the deed: name and location.
- field deed parties: Every party on the deed, each with role (seller, buyer, other), entity_type, civil_status, spouse and represented_by. Indexed as nested — see the note below.
- field deed properties: Every property on the deed, each with finca_number, cadastre_number, municipality, area_sqm and area_cuerdas. Indexed as nested.
- field deed priorTitle: The prior title the deed cites: deed_number, notary and year.
- field deed liens: Encumbrances transcribed from the registry entry, as free text.
- field invoice asiento: Registry entry number (asiento) from the presentation receipt.
- field invoice finca: Property (finca) number from the presentation receipt.
- field invoice cadastre: Cadastre number from the presentation receipt.
- field scriptures meta: Provenance: extraction source, model and confidence. Not searchable.

## Deed extraction (scripturesJson)
- deed intro: Puerto Rico transactions can carry the contents of the deed itself, read from the scanned document and its registry presentation receipt: the parties and their civil status, the notary, the finca and cadastre numbers, the registry entry, the prior title and the transcribed encumbrances.
- deed coverage: Coverage is partial and differs per field. Of 3,806,916 Puerto Rico transactions, 1,145,788 (30.1%) carry a deed object. Within those: invoice.asiento on 993,959, deed.parties on 767,949 and deed.sellerName on 426,020. Treat an absent block as “not extracted”, never as “no deed exists”.
- deed nested note: parties[] and properties[] are indexed as nested objects, so a filter on them matches within a single array element rather than across the array. Filtering role=seller together with a name matches only a party that is both, which is what you want when a deed has several parties.
- field col deedNumber: Escritura (deed) number from the fiscal receipt.
- field col deedDate: Date the escritura was granted, from the fiscal receipt.
- field col notary: Notaría that granted the escritura.
- field col matricula: Matrícula inmobiliaria — the registry identifier of the property. Exact-match filterable.
- field col actType: Act type declared on the fiscal receipt (Compraventa, Hipoteca, …).
- deed col note: Colombia carries the same idea from a different document. A COL transaction usually has three fiscal receipts — recibo de caja, impuesto de registro, derechos de registro — and each contributes different fields, so they are merged rather than one being picked. Coverage: 39,517 of 512,637 COL transactions (7.7%) carry the block; within those, deedNumber 39,512, deedDate 39,504, actType 39,477, notary 39,497 and matricula 39,414. scripturesJson on COL holds escrituraNumber, escrituraDate, notary, actType, matricula, nir, solicitante and contribuyente — it has no parties or properties arrays, so the nested note below applies to Puerto Rico only.

# Permits
URL: /en/docs?section=permits

Building and land use permits from municipal registries. Track construction activity, demolitions, and land use changes at the parcel level.
- col coverage: Colombia (col) serves licence decisions from nine public sources, refreshed weekly: Bogotá (the Secretaría Distrital de Planeación's table of executed licences, 2008 onwards, merged with the SINU lot polygons of each decision), city layers for Cartagena (2023 onwards), Barranquilla (2013-2021), Bucaramanga (2020-2022), Pereira (2021 onwards), 13 Cundinamarca municipalities (2014-2021) and Soacha (2023), and the Supernotariado national registry, which covers the 49 municipalities with a curaduría from 2017 and is being backfilled. Colombian records carry applicationNumber (the expediente or radicado), administrativeActNumber, permitTypeRaw, procedureModalityRaw, authorityNameRaw (the curaduría), decisionStatusRaw and decisionOutcome (approved or denied), effectiveAt, address, chip (Bogotá's cadastral CHIP), usesJSON, geometry when the source has one, parcelId and propertyId when the permit is linked, and url, the scanned resolution for registry acts. Registry acts gain type, decision, address and dates as their documents are read.

## Query Parameters

## Response Fields

## Example Request

## Example Response
- filter permitType: Permit classification (new_construction, demolition, renovation, land_use…)
- filter date gte: Earliest permit date (ISO 8601)
- filter date lte: Latest permit date (ISO 8601)
- filter cityId: Filter by city
- filter status: approved | pending | rejected | expired (COL)
- filter parcelId: All permits for a parcel (COL)
- field id: Unique permit identifier
- field permitType: Permit classification
- field date: Permit issue or registration date
- field cityId: City reference
- field parcelId: Linked parcel
- field status: approved | pending | rejected | expired
- field name: Permit name/title
- field description: Permit description
- field case: Official case/docket number

# Documents
URL: /en/docs?section=documents

Legal and administrative documents linked to transactions, listings, parcels, or permits. Includes downloadable URLs for deeds, contracts, and certificates.
- availability note before: ⚠ Available for
- availability note and: and
- availability note after: only.

## Query Parameters

## Response Fields

## Example Request

## Example Response
- filter type: Document type (deed, contract, certificate, permit_doc…)
- filter transactionId: All documents for a transaction
- filter parcelId: All documents for a parcel
- filter permitId: All documents for a permit
- filter genericListingId: All documents for a listing
- field id: Unique document identifier
- field name: Document file name or title
- field url: Download URL for the document (files.atlas.red)
- field type: Document type classification (e.g. TRANSACTION, PERMIT)
- field date: Document date (e.g. transaction date)
- field unitNumber: Unit number associated with the document
- field govtId: Government property ID associated with the document
- field sourceId: Internal source identifier
- field createdAt: Record creation timestamp
- field updatedAt: Last update timestamp
- field transactionId: Linked transaction (if type is TRANSACTION)
- field genericListingId: Linked listing (if any)
- field parcelId: Linked parcel (if any)
- field permitId: Linked permit (if any)

# Tenants
URL: /en/docs?section=tenants

Commercial tenants and businesses occupying properties. Includes contact information, location, photos, and links to parcels and properties.

## Query Parameters

## Response Fields

## Example Request

## Example Response
- filter name like: Search tenant name (case-insensitive)
- filter parcelId: All tenants in a parcel
- filter propertyId: All tenants in a property
- filter sectorId: Filter by sector
- filter address like: Search by address substring
- field id: Unique tenant/business identifier
- field name: Business or tenant name
- field url: Source URL (e.g. OpenStreetMap, business portal)
- field phones: Contact phone numbers
- field pictures: Photo URLs
- field emails: Contact email addresses
- field websites: Additional website URLs
- field address: Street address
- field descriptionText: Business description
- field sectorId: Sector reference
- field subsectorId: Subsector reference
- field microsectorId: Microsector reference
- field parcelId: Linked parcel
- field propertyId: Linked property
- field sourceId: Internal source identifier
- field createdAt: Record creation timestamp
- field updatedAt: Last update timestamp
- field extractedAt: Date data was last extracted from source
- field parcel: Nested parcel record

# Taxes
URL: /en/docs?section=taxes

Per-parcel property tax records. Puerto Rico (pri) serves the CRIM valuation breakdown (land, structure, machinery), exemptions and the taxable base. Colombia (col) serves the avalúo catastral (the cadastral valuation), one record per fiscal year (vigencia).
- col coverage: Colombia (col): a property has one record per vigencia (fiscal year), back to about 1996 where municipal records exist. totalValuation is the avalúo catastral in COP, with valuationBasis official (published by the cadastre) or modeled. annualTax is present only where a real municipal bill was read (taxBasis billed; pilot cities Villavicencio and Popayán): no tax amount is estimated anywhere else. Colombian records carry govtId (the 30-digit NPN), vigencia, land, structure, totalValuation, valuationBasis, destinoEconomico, estrato (1-6), tarifaPerMil, annualTax, taxBasis and address; machinery, exemption, exoneration and taxable are Puerto Rico only. Amounts are whole units of the market currency (USD for pri, COP for col).

## Query Parameters

## Response Fields

## Example Request

## Example Response
- filter propertyId: Restrict results to a specific property.
- filter totalValuation gte: Minimum total valuation (pri: land + structure + machinery; col: the avalúo catastral).
- filter taxable gte: Minimum taxable value after exemptions and exonerations (pri).
- filter vigencia: Fiscal year of the avalúo, e.g. 2025 (col).
- filter taxBasis: billed to keep only records with a real municipal bill (col).
- filter estrato: Socio-economic stratum, 1-6 (col).
- filter address like: Prefix-match on the parcel address.
- field id: Tax record identifier.
- field propertyId: Related property.
- field parcelId: Related parcel.
- field address: Parcel address as captured from the tax roll.
- field land: Assessed land value.
- field structure: Assessed structure (improvements) value.
- field machinery: Assessed machinery value.
- field totalValuation: Total assessed value: land + structure + machinery (pri); the avalúo catastral (col).
- field exemption: Homestead/partial exemption applied.
- field exoneration: Additional exoneration applied (if any).
- field taxable: Final taxable base after exemption and exoneration.
- field govtId: National cadastral number (NPN, 30 digits).
- field vigencia: Fiscal year the record belongs to.
- field valuationBasis: official (published by the cadastre) | modeled.
- field destinoEconomico: Cadastral economic use (destino económico).
- field estrato: Socio-economic stratum, 1-6.
- field tarifaPerMil: Property-tax rate in per mil (‰).
- field annualTax: Annual property tax (predial) in COP. Present only when taxBasis is billed.
- field taxBasis: billed (read from a real municipal bill) | estimated. Only billed amounts are a tax actually charged.

# Short-Term Rentals
URL: /en/docs?section=short-term-rentals

Vacation and short-stay rental listings from Airbnb and VRBO in one entity: one record per listing with its nightly price index, availability and estimated occupancy. The source field names the platform (airbnb, vrbo); filter or group by it to separate or compare them.
- coverage: Puerto Rico (pri) and Colombia (col). Measured 2026-09-24: pri 24,968 listings (24,214 Airbnb, 754 VRBO); col 81,538 Airbnb listings (VRBO not crawled in Colombia yet). Prices are USD in both markets.
- endpoints: GET /v1/data/{market}/shortTermRentals and GET /v1/data/{market}/shortTermRentals/{id} (market = pri or col; id = genericListingId), plus the shared /stats, /trend, /top-by, /pivot, /points and /market-report endpoints and text search.
- credit cost: 5 credits per record returned; 5 credits per aggregator call (stats, top-by, pivot, market report).
- price note: Prices are USD per night, never a monthly rent. On Airbnb, currentNightlyPrice is the quote for a 3-night stay 30 days out and nightlyPrice7n the 7-night quote. On VRBO, currentNightlyPrice is the search price for a stay without dates and there is no 7-night quote.
- occupancy note: Occupancy and revenue are estimates from calendar captures (method calendar_flip_v2): a night open on the listing's previous capture (any date within 30 days) and closed on the next counts as booked, so a host-blocked night reads as booked too. Quote them as estimated.
- location note: Location is approximate. Airbnb publishes a point moved about 150 m (locationPrecision fuzzed_150m); VRBO rows carry the point VRBO reports (reported). Neither identifies a parcel: parcelId and buildingId are best-effort matches.
- vrbo note: VRBO rows carry no rating, reviewsCount, isSuperhost or host fields.

## Query Parameters
- filter source: Platform: airbnb | vrbo
- filter propertyType: Apartment, House, Condo, Townhome, Studio, Hospitality
- filter citySlug: City slug, e.g. san-juan
- filter currentNightlyPrice: Nightly price in USD (currentNightlyPrice.gte / .lte)
- filter bedrooms: Bedrooms (bedrooms.gte), from the listing detail page
- filter active: Listing still shown by the platform (boolean)
- filter near bbox: Radius or viewport around location; see Geospatial Queries

## Response Fields
- field genericListingId: Record id
- field source: Platform: airbnb | vrbo
- field externalId: The platform's own listing id
- field url: Listing URL on the platform
- field title: Listing title
- field propertyType: Structure type
- field cityName: City name (citySlug, neighborhoodName and neighborhoodSlug alongside)
- field location: Approximate point (see locationPrecision)
- field currentNightlyPrice: Headline nightly price, USD
- field nightlyPrice7n: Nightly price of the 7-night quote (Airbnb)
- field medianNightlyPrice90d: Median nightly price over 90 days of captures
- field availability30d: Share of the next 30 nights open (availability60d for 60)
- field occupancy30d: Estimated occupancy over the next 30 nights (occupancy60d for 60)
- field bookedNightsLast30dEst: Nights estimated booked over the last 30 capture days
- field monthlyMetrics: Monthly rollup: month, nightsObserved, bookedNightsEst, occupancyEst, medianNightlyPrice, revenueEst, reviewsDelta
- field latestOccupancyEst: Current month's estimated occupancy (latestMonth, latestRevenueEst and latestMedianNightlyPrice alongside)
- field rating: Guest rating 0-5 and reviewsCount (Airbnb)
- field guests: Guests, bedrooms, beds and bathrooms from the listing detail page
- field parcelId: Best-effort parcel match (propertyId and buildingId alongside)
- field status: FOR_RENT or REMOVED_RENT; active, firstSeenAt, lastSeenAt and daysListed alongside

## Stats and dimensions
- stats list: newInLast30d, byPropertyType, byStatus, byCity, bySource, priceStats, pricePercentiles, nightlyPrice7nStats, medianNightlyPrice90dStats, occupancy30dStats, occupancy60dStats, availability30dStats, revenueEstStats, ratingStats, reviewsStats, superhostCount, activeCount, avgDaysListed
- groupby dimensions: source, propertyType, roomTypeLabel, placeLabel, status, isSuperhost, citySlug, cityId, neighborhoodSlug, neighborhoodId, zipCodeId, regionId

# Buildings
URL: /en/docs?section=buildings

Building records with address information and stratum classification. Buildings group multiple properties and units within the same physical structure.
- availability note before: ⚠ Available for
- availability note and: and
- availability note after: only.

## Query Parameters

## Response Fields

## Example Request

## Example Response
- filter type: Building type e.g. Condominium
- filter cityId: Filter by city
- filter name like: Search by building name substring
- field id: Unique building identifier
- field name: Building name (e.g. Edificio Uno 83)
- field type: Building type classification (e.g. Condominium)
- field geometry: Building location coordinates
- field cityId: City reference

# News
URL: /en/docs?section=news

Real-estate market news articles indexed per market — headline, description, source link, category tags and publish date. Query like any entity: filter by date range, sort by date, or text-search the title.

## Response fields
- field id: Article id.
- field title: Headline.
- field description: Article summary/body.
- field link: URL of the original article at the source.
- field category: Category tags (returned for display). Note: not filterable or aggregatable in the index.
- field date: Publish date.
- field sourceLogo: Logo URL of the source outlet.
- filters note: Filterable fields: date (date.gte / date.lte), title (title.like), active and reportsResearch (booleans). Sort by date (default sort=date:desc). category is returned but cannot be filtered or grouped.

# Market Stats (Aggregator)
URL: /en/docs?section=aggregator-stats
- description before: Returns pre-computed
- description aggregations: aggregations
- description after: for a given (market, entity) pair — counts, distributions, ranges, and bucket breakdowns — in a single call, without paging through raw records.
- tier note before: Billed as one aggregator call —
- tier note business: 5 to 15 credits
- tier note after: depending on the entity, with no minimum plan. Results are cached for 10 minutes per (market, entity, filter) combination.

## Availability
- availability pri before: Puerto Rico (
- availability pri after: ): all 10 entities (properties, listings, parcels, transactions, permits, tenants, documents, buildings, taxes, shortTermRentals).
- availability col before: Colombia (
- availability col after: ): all 10 entities (properties, listings, parcels, transactions, permits, tenants, documents, buildings, taxes, shortTermRentals).

## Query Parameters
- query params note: Pagination, sorting, and field selection do not apply — the response is a fixed set of aggregations.

## Response Shape
- response shape label envelope: Envelope

## Stats Returned Per Entity
- entity stats description before: Each entity exposes a tailored set of aggregations. Below is the field map — shape of
- entity stats description after: in the response:
- outlier note: On listings, `excludingOutliers` repeats the price aggregates with the documents ingest flagged as `isOutlier` removed (scraped placeholder prices such as a "call for price" listing indexed at 99,900,000). Use it for any money total or average; the top-level `priceStats` is the unfiltered figure. Only the listings indices carry the flag today.

## Scoping stats to an area
- geo scope description: The aggregator accepts the same `near` radius and `bbox` viewport parameters as the list endpoint, on the entities that carry coordinates. Use them to get a median or a count for one neighborhood or one map box in a single call, rather than paging records and averaging client-side.

## Example Request

## Credit Cost
- credit cost part1: Aggregator calls are billed at a flat per-call cost (not per record). The exact value lives in
- credit cost part2: as
- credit cost part3: with a fallback to
- credit cost part4: Check the credits calculator for the current amount per entity.
- filter field: Same filter syntax as the list endpoint. Restricts the dataset the aggregator runs on before computing stats.
- filter field op: Range / comparison operators also supported: gt, gte, lt, lte, in, like, neq, presence.
- field properties: properties
- field properties stats: areaStats (totalArea), byUnitType[]
- field listings: listings
- field listings stats: newInLast30d, byStatus[], byBedrooms[], priceStats, pricePercentiles, areaStats, areaPercentiles, avgDaysOnMarket, excludingOutliers { totalCount, priceStats, pricePercentiles }
- field parcels: parcels
- field parcels stats: byZoningGeneric[], areaStats (totalArea)
- field transactions: transactions
- field transactions stats: newInLast30d, priceStats, pricePercentiles, volumeByMonth[], byYear[]
- field permits: permits (pri)
- field permits stats: newInLast30d, byCategory[], byStatus[]
- field tenants: tenants
- field tenants stats: none — occupant records carry no aggregatable category, metric or date. The call returns totalCount only.
- field documents: documents
- field documents stats: newInLast30d, byType[], byYear[]
- field buildings: buildings
- field buildings stats: byType[]
- field taxes: taxes (pri, col)
- field taxes stats: totalValuationStats, totalValuationPercentiles, taxableStats, taxablePercentiles, landStats, structureStats, hasExemption, hasExoneration
- field shortTermRentals: shortTermRentals (pri, col)
- field shortTermRentals stats: newInLast30d, byPropertyType[], byStatus[], byCity[], bySource[], priceStats, pricePercentiles, nightlyPrice7nStats, medianNightlyPrice90dStats, occupancy30dStats, occupancy60dStats, availability30dStats, revenueEstStats, ratingStats, reviewsStats, superhostCount, activeCount, avgDaysListed

# Filtering & Pagination
URL: /en/docs?section=filtering

All list endpoints share the same filter, sort, pagination, and field-selection system.

## Filter Operators

## Example: Combined Filters

## Pagination
- pagination description before: Use
- pagination description and: and
- pagination description after: to paginate through results. Maximum limit is
- pagination description end: per request.
- meta total: Total matching records across all pages
- meta page: Current page
- meta limit: Records per page
- meta totalPages: Total number of pages

# Geospatial Queries
URL: /en/docs?section=geospatial
- description before: Entity records that include geometry fields (properties, parcels, listings, tenants) return GeoJSON geometries. The
- description after before point: field contains either a
- description or: or
- description end: .

## Geometry Fields

## Example: Fetch geometry
- field geometry: Point or Polygon — exact parcel/property footprint
- field centroid: Centroid point of a polygon (parcels)
- field location: Point geometry (listings, tenants)

## Distance search
- near description: Append a top-level `near` query parameter to filter results to records within a radius of a coordinate. Format: `near=lat,lng[,radius]`. A bare number in the radius slot is interpreted as meters; valid suffixes are m, km, mi, yd, ft. If the radius is omitted, it defaults to 100m.

## Parameters
- near param lat: Latitude in decimal degrees, between -90 and 90.
- near param lng: Longitude in decimal degrees, between -180 and 180.
- near param radius: Optional. Radius around the point. Accepts a bare number (meters) or a number with a unit suffix: m, km, mi, yd, ft. Defaults to 100m when omitted.

## Supported entities
- near supported description: Today, near is supported on entities whose index has a top-level geo_point: parcels (matched against centroid) and listings (matched against location). On /v1/search, the filter is applied only to the buckets that support it; the response includes a meta.geoApplied list naming which buckets used the geo filter.
- near unsupported description: Other entities (tenants, properties, permits, transactions, documents, buildings, taxes) return a 400 GEO_NOT_SUPPORTED error when called with near. Resolve the coordinate to a parcel or listing first and look those up by id.

## Example: Find parcels within 500m of a point

## Example: Multi-entity search with near

## Errors
- near error invalid: 400 INVALID_GEO_FILTER — bad near format, out-of-range lat/lng, or unknown radius unit.
- near error unsupported: 400 GEO_NOT_SUPPORTED — the entity index has no top-level geo_point field.

## Viewport search
- bbox description: Use the top-level `bbox` query parameter to filter results to a rectangle instead of a circle — the natural fit for a map viewport. Format: `bbox=swLng,swLat,neLng,neLat`, four decimal degrees with LONGITUDE FIRST in each pair. The south-west corner must be south and west of the north-east corner. `bbox` and `near` can be combined.
- bbox supported description: Supported on the same entities as near (parcels and listings) and on the market stats endpoint, so counts and medians can both be scoped to the visible box in one call. Other entities return 400 GEO_NOT_SUPPORTED. Prefer bbox over near whenever you have map corners: approximating a rectangle with a radius answers a different question.

## Example: Listings inside a map viewport
- bbox error invalid: 400 INVALID_GEO_FILTER — bbox is not four numbers, or the corners are not ordered south-west then north-east.

# Text Search
URL: /en/docs?section=text-search

Full-text search across Atlas entities. A single call runs a multi-match query and returns matching records from up to nine buckets (listings, parcels, transactions, properties, tenants, permits, documents, news, cities) side by side — backed by the same OpenSearch index that powers the portal's search bar.

## Query Parameters

## Response Fields

## Example Request

## Example Response
- param q: Search text. Required.
- param market: Market code. Must be `pri` or `col`. Required.
- param types: Comma-separated list of buckets to search. Allowed values: listings, parcels, transactions, properties, tenants, permits, documents, news, cities. Defaults to all nine.
- param limit: Maximum results per bucket. Default: 3, maximum: 25.
- param includes: Per-bucket field selection using bracket syntax, e.g. `includes[tenants]=id,name,parcel.photos`. Accepts dot-notation to pull relation fields (`sector.name`, `parcel.id`). When omitted for a bucket, a sensible default include set is applied. Unknown bucket names return 400.
- field data: Object keyed by bucket name. Each key present in `types` maps to the array of matching records for that entity.
- field data listings: Array of active and historical listings matching the query
- field data parcels: Array of parcels matching the query
- field data transactions: Array of transactions matching the query
- field data properties: Array of properties matching the query
- field data tenants: Array of commercial tenants matching the query
- field data permits: Array of permits matching the query
- field data documents: Array of documents matching the query
- field data news: Array of news items matching the query
- field data cities: Array of cities matching the query
- field meta: Echoes back the request parameters: query, market, requested types, and per-bucket limit.

# Discovering Location IDs
URL: /en/docs?section=location-ids

Filters like filter[cityId], filter[neighborhoodId], filter[sectorId] and filter[buildingId] accept the internal UUIDs that Atlas uses to identify each geographic entity. Use the Locations API below to translate names ("Bogotá", "El Poblado") into IDs you can plug into the Data API. These endpoints are free — no credits are charged.

## Recommended flow
- flow step 1: List the geographies you care about once (cities → neighborhoods → sectors) and cache them locally. IDs are stable.
- flow step 2: When a user filters by name on your side, look up the cached UUID and pass it to the Data API as filter[cityId]= / filter[neighborhoodId]= / etc.
- flow step 3: Need to refresh? Re-call the same endpoint with the same parameters — responses are paginated via ?from= & ?size= (max 200).
- flow step 4: Alternatively: every parcels / properties / listings response already includes cityId, neighborhoodId and sectorId — you can harvest IDs from real data on the fly.

## Endpoints
- endpoint markets: List markets/countries. Pass includeGeometry=true for the country boundary polygon.
- endpoint regions: List regions / departamentos for a market.
- endpoint cities: List cities (optionally narrowed to a single region).
- endpoint neighborhoods: List neighborhoods (optionally narrowed to a single city). Use this to populate filter[neighborhoodId].
- endpoint sub neighborhoods: List sub-neighborhoods for one or more neighborhoods. neighborhoodIds is a comma-separated UUID list.
- endpoint sectors: Sector taxonomy used by filter[sectorId] on parcels/permits/transactions. A property-use classification (e.g. Office, Retail, Land), not a geographic area.
- endpoint sub sectors: Sub-sector taxonomy (filter[subsectorId]). Pass sectorId to scope to one parent sector.
- endpoint micro sectors: Micro-sector taxonomy (filter[microsectorId]). Pass subsectorId to scope to one parent sub-sector.
- endpoint buildings: Prefix-match buildings by name. Pass cityId/neighborhoodId to narrow the search. Use the returned id with filter[buildingId].
- endpoint zipcodes: Search zip codes by substring. Returns id + cityId + neighborhoodId so you can chain into the other filters.
- geometry note: Add includeGeometry=true to markets, regions, cities, neighborhoods, sub-neighborhoods and zip-codes to get the GeoJSON boundary polygon (omitted by default). Polygons are large — use simplify=<degrees> (higher = coarser) to shrink them. Sectors/sub-sectors/micro-sectors are a use classification and have no geometry.

## Example: list all cities in Colombia
- example cities description: Use this to build an in-app autocomplete or to seed a local cache of city UUIDs.

## Example: list neighborhoods inside a given city
- example neighborhoods description: Pass the cityId you just received to scope the result set.

## Example: filter parcels by the resolved neighborhood
- example parcels description: Drop the UUID straight into filter[neighborhoodId] on any data endpoint.

## Or: discover IDs from existing data
- discover from payload description: Every Data API record already includes the location IDs. If you don't want to call the lookup endpoints, request just the ID fields and harvest them from a single response.

## Pricing
- pricing description: Free — these endpoints don't consume credits. They are rate-limited by plan to prevent abuse via unbounded crawls.

## Report API

# Report API Overview
URL: /en/docs?section=report-overview

The Report API generates on-demand valuation and comparables reports using RED Atlas's AVM models. Reports are stored server-side and can be retrieved by ID.

## Endpoints
- endpoint avm: Generate an AVM valuation report
- endpoint comparables: Generate market comparables (listings + transactions)
- endpoint list: List all reports generated by your key
- endpoint get: Get a single report by ID

## Report Status
- status processing: Report is being generated (rarely seen — generation is synchronous)
- status completed: Report generated successfully. Result is in the result field.
- status failed: Generation failed. errorMessage contains the reason.

# AVM Report
URL: /en/docs?section=avm-report

Generates an Automated Valuation Model (AVM) estimate for a property based on its location, type, and physical characteristics. Uses RED Atlas's proprietary ML models trained on millions of transactions and listings.

## Request Body

## Example Request

## Example Response
- field market: Market code: col | pri | arg | mex | ecu | per | pan
- field location lat: Latitude
- field location lon: Longitude
- field propertyType: apartment | house | office | commercial | land
- field listingType: for_sale | for_rent
- field builtArea: Built area in m² (optional)
- field lotArea: Lot area in m² (optional)
- field rooms: Number of bedrooms (optional)
- field toilets: Number of bathrooms (optional)
- field parkingSpaces: Parking spaces (optional)
- field yearBuilt: Year of construction (optional)

# Property Profile
URL: /en/docs?section=property-profile

Property Profile reports are planned for a future release. They will combine Data API property details with AVM valuation and market comparables into a single enriched report.

# Market Comparables
URL: /en/docs?section=market-comparables

Finds the most similar nearby listings and transactions for a given property. Returns a ranked list of comparables with distance, price, and area data.

## Request Body

## Example Request

## Example Response
- fetch ids note: Use the returned IDs to fetch full listing/transaction details via the Data API:
- field market: Market code
- field location lat: Latitude
- field location lon: Longitude
- field propertyType: apartment | house | office | commercial | land
- field listingType: for_sale | for_rent
- field builtArea: Built area in m² (optional)
- field price: Current asking/reference price (optional)
- field pricePerBuiltSqm: Price per m² (optional)
- field rooms: Bedrooms (optional)
- field toilets: Bathrooms (optional)
- field returnSize: Number of comparables to return. Default 10, max 50.
- field onlyActiveListings: Restrict listings comparables to active only. Default: true
- field includeTransactions: Include transaction comparables. Default: true

## SDKs & Libraries

# Claude & AI Assistants (MCP)
URL: /en/docs?section=mcp-connector

Talk to the RED Atlas API in natural language. Our remote MCP (Model Context Protocol) server lets AI assistants such as Claude query live market data, run valuations and read this documentation on your behalf, using your own account and plan.

## Connector URL
- url description: Add this URL wherever your AI client asks for a remote MCP server:

## Authentication & billing
- auth description: When you connect, you sign in with your developer portal email and password (OAuth). No API key is exposed to the assistant. The connection is tied to your account and can be revoked at any time.
- auth credits note: Assistant calls are metered exactly like regular API calls: they consume your plan's monthly credits, and the aggregate and premium tools cost more per call than a plain record read. Track everything in the Usage dashboard.

## Claude (web, desktop, mobile)
- claude step1: Open Settings > Connectors and find RED Atlas API in the connector directory — it is listed publicly, so there is no URL, client ID or secret to paste.
- claude step2: Click Connect, sign in with your developer-portal email and password, then click Authorize.
- claude step3: In a chat, open the connector menu to allow the tools you want — the read-only query tools can be left on "always allow"; report creation asks each time.
- claude custom note: Adding it by URL instead (a self-hosted client, or any assistant that does not read Claude's directory): choose Add custom connector, paste the connector URL above and leave OAuth Client ID and Secret empty.
- claude team note: On Claude Team/Enterprise plans only an organization Owner can add the connector (Organization settings > Connectors). Keep Individual sign-in enabled so every member connects with their own RED Atlas account.

## Claude Code
- claude code description: One command registers the connector by URL — the directory listing is not used by the CLI. Authentication opens in your browser:

## Connecting from your AI assistant
- connect intro: The connector follows the open MCP standard, so the same URL works across assistants. It is added once per workspace; each user then signs in with their own developer-portal account.

## ChatGPT (OpenAI)
- chatgpt step1: In ChatGPT, open Settings > Connectors (available on Plus, Pro, Business and Enterprise) and choose Add custom connector / MCP server.
- chatgpt step2: Paste the connector URL; leave any client id/secret blank.
- chatgpt step3: Authorize with your developer-portal account, then enable the connector in a chat or project.

## Gemini
- gemini description: Gemini CLI connects over MCP. Add the server to your ~/.gemini/settings.json (or a project .gemini/settings.json); the OAuth sign-in opens in your browser on first use.

## Grok & X
- grok step1: In Grok (grok.com) or X, open Settings > Connectors > New connector > Custom.
- grok step2: Paste the connector URL as the remote MCP server.
- grok step3: Complete the OAuth sign-in with your developer-portal account.

## Smithery
- smithery description: Smithery is a public MCP directory whose gateway proxies your client to this server, so it works from any Smithery-compatible client without pasting a URL. The listing is
- smithery link label: RED Atlas API on Smithery
- smithery step1: Open the listing and click Connect — there is nothing to configure, because access is negotiated over OAuth rather than an API key.
- smithery step2: Sign in with your developer-portal email and password and click Authorize. Calls are metered against the same plan credits as every other client.

## Available tools
- tools description: The connector exposes the documented API surface as 18 tools. The assistant picks them automatically based on your question. The tool list is discovered over MCP at connection time, so tools we add show up without any change on your side — reconnect the connector if an assistant is still on an older list.
- tools col tool: Tool
- tools col description: Description
- tool atlas query data: List records (properties, listings, parcels, ...) with filters, sorting and pagination. Supports the near radius and bbox viewport filters. Consumes credits per record.
- tool atlas get record: Fetch a single record by id. Consumes credits.
- tool atlas get stats: Aggregated market statistics, optionally scoped to a radius (near) or a map viewport (bbox). Fixed credit cost (5-15 depending on the entity).
- tool atlas market report: Profile a market in one call: stats, a 12-month trend and an optional ranked breakdown. Fixed credit cost.
- tool atlas top by: Rank and count records by a dimension, e.g. listings per municipality or per brokerage. Fixed credit cost.
- tool atlas pivot: Cross-tabulate two dimensions; either axis may be a date, which returns a time series per group. Fixed credit cost.
- tool atlas velocity: How fast a market is moving: new records this period vs the previous one, with the absolute and percent change. Fixed credit cost.
- tool atlas search: Free-text search across entities. Consumes credits per call.
- tool atlas lookup location: Resolve city, neighborhood and region names into filter ids. Free.
- tool atlas list entities: Discover which entity types a market offers. Free.
- tool atlas get parcel contacts: People RED Atlas holds for a parcel (brokers, permit professionals): names, roles and provenance, never phones or emails. Free.
- tool atlas request contacts: Request the phone numbers and emails of those people. Returns a receipt; the details go to your RED Atlas repository and inbox, never into the chat. Charges the contacts price per contact your organization has not unlocked yet.
- tool atlas enrich contacts: Contact enrichment (skip-trace, premium) for a person or address. Returns who was found plus a receipt; the details go to your repository. Charges the contacts_enriched price only when it unlocks someone new; a no-match costs 0.
- tool atlas create avm report: Start an automated valuation (AVM) report. 10 credits for JSON, 15 with the PDF.
- tool atlas create comparables report: Start a market comparables report. 6 credits.
- tool atlas comparable sales: Comparable recorded sales near a property, with distance, price per m2 and the medians already computed. Runs the comparables report and waits for the result, so it is one call instead of create-then-poll. 6 credits.
- tool atlas asset class report: Profile one asset class in a single call: for-sale and for-rent aggregates, a building-class split, top municipalities, velocity and the total stock of that use. Billed as the ~7 aggregator calls it runs.
- tool atlas list reports: List your generated reports. Free.
- tool atlas get report: Fetch a report result and its shareable link. Free.
- tool atlas read docs: Read this documentation so answers cite real parameters. Free.

## Things you can ask
- example1: How many houses are for sale in San Juan under $500,000?
- example2: Run an AVM for this address and give me the estimated value.
- example3: Write a Python script that pulls last month's transactions in Condado.

## Other AI clients
- other clients description: The connector follows the open MCP standard and also works with other MCP-capable clients, such as ChatGPT custom connectors and MCP-enabled IDEs. Point the client at the same URL and sign in with your developer portal account.

## Help

# Discord
URL: /en/docs?section=discord-help

Join our Discord if you want direct help while building with the API.
- card title: Talk with our developers
- card description: You can talk with our developers for any question about the API and the community.
- cta: Join Discord

# Contact
URL: /en/docs?section=contact-support

Use our contact page when you need help from the team, want to discuss sales, or have account-related questions.
- card title: Contact the RED Atlas team
- card description: Open the contact page to reach support, ask commercial questions, or send us a detailed request.
- cta: Open contact page

# Documentation
URL: /en/docs?section=metadata

Complete API reference, guides, and SDKs for integrating the RED Atlas real estate data API. Get started in minutes.

# undefined
URL: /en/docs?section=content
- copy: Copy
- copied: Copied
- premium badge: Extra credits
- table field: Field
- table type: Type
- table description: Description
- filter parameter: Parameter