Measurabl Listed Real Estate Reports API

openapi: 3.2.0
info:
  title: ESGx Securities Listed Real Estate Reports API
  version: v0
  description: '## Quick Start Guide


    1. Authorize using your client credentials (key and secret).

    2. Make a request to get a list of available data_set files


    * [Authentication](https://support.measurabl.com/hc/en-us/articles/15889532915085-How-do-I-authenticate-with-Measurabl-s-Core-API-)

    * [Usage/Rate Limits](https://support.measurabl.com/hc/en-us/articles/15889355100429-Core-API-Usage-Rate-Limits)

    * [Pagination & Filtering](https://support.measurabl.com/hc/en-us/articles/15889550313101-Core-API-Pagination-Filtering-Requests)


    ### Response Format


    Each endpoint response complies with the [JSON-API Specification](https://jsonapi.org/) which has many available [client libraries](https://jsonapi.org/implementations/#client-libraries).

    '
servers:
- url: https://api.measurabl.com/insights/v0
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: Listed Real Estate Reports
paths:
  /insights/v0/listed_real_estate_reports/{id}/building_level/{data_set}/download:
    get:
      summary: Downloads the export file
      description: 'Provides a redirect to download the export file.

        The url in the redirect has an expiration, typically of 5 minutes.

        '
      tags:
      - Listed Real Estate Reports
      security:
      - OAuth2: []
      parameters:
      - name: id
        in: path
        description: 'Example: <em>august-2023</em>'
        required: true
        schema:
          type: string
      - name: data_set
        in: path
        description: 'Example: <em>t-12-carbon-estimates</em>'
        required: true
        schema:
          type: string
      responses:
        '302':
          description: Export is downloaded via redirect to pre-signed URL
          headers:
            Location:
              type: string
              description: URL of file location
          content:
            text/html:
              example: ''
        '200':
          description: Export is not ready yet
          content:
            application/vnd.api+json:
              example:
                data:
                  id: july-2021/building_level/t-12-carbon-estimates
                  type: listedRealEstateDataSets
                  attributes:
                    dataSet: carbon_estimates
                    timePeriod: T-12
                    status: PROCESSING
                    createdAt: '2026-07-16T13:20:45.373Z'
                    updatedAt: '2026-07-16T13:20:45.373Z'
                meta:
                  message: The export is not ready yet. Check the status with http://www.example.com/insights/v0/listed_real_estate_reports/july-2021/building_level/t-12-carbon-estimates
  /insights/v0/listed_real_estate_reports/{id}/building_level:
    get:
      summary: Retrieves the data sets available for a Listed Real Estate Report
      description: 'Provides information about the company-level data sets for a given Listed Real Estate Report

        '
      tags:
      - Listed Real Estate Reports
      security:
      - OAuth2: []
      parameters:
      - name: id
        in: path
        description: 'Example: <em>august-2023</em>'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Building Level Listed Real Estate Data Sets
          content:
            application/vnd.api+json:
              example:
                data:
                - id: july-2024/building_level/t-12-carbon-estimates
                  type: listedRealEstateDataSets
                  attributes:
                    dataSet: carbon_estimates
                    timePeriod: T-12
                    status: READY
                    createdAt: '2026-07-16T13:20:45.842Z'
                    updatedAt: '2026-07-16T13:20:45.865Z'
              schema:
                $ref: '#/components/schemas/json_api'
        '404':
          description: Listed Instance Slug is not found
          content:
            application/vnd.api+json:
              example:
                errors:
                - status: '404'
                  title: Not Found
                  detail: Page not found
              schema:
                $ref: '#/components/schemas/json_api'
        '403':
          description: when authenticated but not authorized
          examples:
            application/vnd.api+json:
              errors:
              - status: '403'
                title: Forbidden
                detail: Access Denied
          content:
            application/vnd.api+json:
              example:
                errors:
                - status: '403'
                  title: Forbidden
                  detail: Access Denied
              schema:
                $ref: '#/components/schemas/json_api'
  /insights/v0/listed_real_estate_reports/{id}/building_level/{data_set}:
    get:
      summary: Retrieves a Listed Real Estate Report Building Level Data Set
      description: 'Provides information about a building-Level data set.

        The fileChecksum provided is a Base64 encoded MD5 hash of the file. This can be checked using:

        `openssl md5 -binary <filename> | base64`

        '
      tags:
      - Listed Real Estate Reports
      security:
      - OAuth2: []
      parameters:
      - name: id
        in: path
        description: 'Example: <em>august-2023</em>'
        required: true
        schema:
          type: string
      - name: data_set
        in: path
        description: 'Example: <em>t-12-carbon-estimates</em>'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Building Level Listed Real Estate Report has been processed successfully
          content:
            application/vnd.api+json:
              example:
                data:
                  id: july-2021/building_level/t-12-carbon-estimates
                  type: listedRealEstateDataSets
                  attributes:
                    dataSet: carbon_estimates
                    timePeriod: T-12
                    status: READY
                    createdAt: '2026-07-16T13:20:46.211Z'
                    updatedAt: '2026-07-16T13:20:46.234Z'
                    downloadLink: http://localhost:3000/insights/v0/listed_real_estate_reports/july-2021/building_level/t-12-carbon-estimates/download
                    fileChecksum: null
              schema:
                $ref: '#/components/schemas/json_api'
        '404':
          description: Data Set does not exist
          content:
            application/vnd.api+json:
              example:
                errors:
                - status: '404'
                  title: Not Found
                  detail: Page not found
              schema:
                $ref: '#/components/schemas/json_api'
        '403':
          description: when authenticated but not authorized
          examples:
            application/vnd.api+json:
              errors:
              - status: '403'
                title: Forbidden
                detail: Access Denied
          content:
            application/vnd.api+json:
              example:
                errors:
                - status: '403'
                  title: Forbidden
                  detail: Access Denied
              schema:
                $ref: '#/components/schemas/json_api'
  /insights/v0/listed_real_estate_reports/{id}/company_level/{data_set}/download:
    get:
      summary: Downloads the export file
      description: 'Provides a redirect to download the export file.

        The url in the redirect has an expiration, typically of 5 minutes.

        '
      tags:
      - Listed Real Estate Reports
      security:
      - OAuth2: []
      parameters:
      - name: id
        in: path
        description: 'Example: <em>august-2023</em>'
        required: true
        schema:
          type: string
      - name: data_set
        in: path
        description: 'Example: <em>t-12-carbon-estimates</em>'
        required: true
        schema:
          type: string
      responses:
        '302':
          description: Export is downloaded via redirect to pre-signed URL
          headers:
            Location:
              type: string
              description: URL of file location
          content:
            text/html:
              example: ''
        '200':
          description: Export is not ready yet
          content:
            application/vnd.api+json:
              example:
                data:
                  id: july-2021/company_level/t-12-carbon-estimates
                  type: listedRealEstateDataSets
                  attributes:
                    dataSet: carbon_estimates
                    timePeriod: T-12
                    status: PROCESSING
                    createdAt: '2026-07-16T13:20:47.046Z'
                    updatedAt: '2026-07-16T13:20:47.046Z'
                meta:
                  message: The export is not ready yet. Check the status with http://www.example.com/insights/v0/listed_real_estate_reports/july-2021/company_level/t-12-carbon-estimates
  /insights/v0/listed_real_estate_reports/{id}/company_level:
    get:
      summary: Retrieves the company-level data sets for a Listed Real Estate Report
      description: 'Provides information about the company-level data sets for a given Listed Real Estate Report

        '
      tags:
      - Listed Real Estate Reports
      security:
      - OAuth2: []
      parameters:
      - name: id
        in: path
        description: 'Example: <em>august-2023</em>'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Company Level Listed Real Estate Report Data Sets
          content:
            application/vnd.api+json:
              example:
                data:
                - id: july-2026/company_level/t-12-carbon-estimates
                  type: listedRealEstateDataSets
                  attributes:
                    dataSet: carbon_estimates
                    timePeriod: T-12
                    status: READY
                    createdAt: '2026-07-16T13:20:47.532Z'
                    updatedAt: '2026-07-16T13:20:47.556Z'
              schema:
                $ref: '#/components/schemas/json_api'
        '404':
          description: Listed Instance Slug is not found
          content:
            application/vnd.api+json:
              example:
                errors:
                - status: '404'
                  title: Not Found
                  detail: Page not found
              schema:
                $ref: '#/components/schemas/json_api'
        '403':
          description: when authenticated but not authorized
          examples:
            application/vnd.api+json:
              errors:
              - status: '403'
                title: Forbidden
                detail: Access Denied
          content:
            application/vnd.api+json:
              example:
                errors:
                - status: '403'
                  title: Forbidden
                  detail: Access Denied
              schema:
                $ref: '#/components/schemas/json_api'
  /insights/v0/listed_real_estate_reports/{id}/company_level/{data_set}:
    get:
      summary: Retrieves a Listed Real Estate Report Company Level Data Set
      description: 'Provides information about a company-level data set.

        The fileChecksum provided is a Base64 encoded MD5 hash of the file. This can be checked using:

        `openssl md5 -binary <filename> | base64`

        '
      tags:
      - Listed Real Estate Reports
      security:
      - OAuth2: []
      parameters:
      - name: id
        in: path
        description: 'Example: <em>august-2023</em>'
        required: true
        schema:
          type: string
      - name: data_set
        in: path
        description: 'Example: <em>t-12-carbon-estimates</em>'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Company Level Listed Real Estate Report has been processed successfully
          content:
            application/vnd.api+json:
              example:
                data:
                  id: july-2024/company_level/t-12-carbon-estimates
                  type: listedRealEstateDataSets
                  attributes:
                    dataSet: carbon_estimates
                    timePeriod: T-12
                    status: READY
                    createdAt: '2026-07-16T13:20:47.906Z'
                    updatedAt: '2026-07-16T13:20:47.929Z'
                    downloadLink: http://localhost:3000/insights/v0/listed_real_estate_reports/july-2024/company_level/t-12-carbon-estimates/download
                    fileChecksum: null
              schema:
                $ref: '#/components/schemas/json_api'
        '404':
          description: Data Set does not exist
          content:
            application/vnd.api+json:
              example:
                errors:
                - status: '404'
                  title: Not Found
                  detail: Page not found
              schema:
                $ref: '#/components/schemas/json_api'
        '403':
          description: when authenticated but not authorized
          examples:
            application/vnd.api+json:
              errors:
              - status: '403'
                title: Forbidden
                detail: Access Denied
          content:
            application/vnd.api+json:
              example:
                errors:
                - status: '403'
                  title: Forbidden
                  detail: Access Denied
              schema:
                $ref: '#/components/schemas/json_api'
  /insights/v0/listed_real_estate_reports:
    get:
      summary: Returns all listed real estate reports
      tags:
      - Listed Real Estate Reports
      security:
      - OAuth2: []
      parameters:
      - name: page
        in: query
        schema:
          type: integer
      - name: pageSize
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: list of listed real estate reports
          content:
            application/vnd.api+json:
              example:
                data:
                - id: july-2026
                  type: listedRealEstateReports
                  attributes:
                    name: July 2026
                    status: PROCESSING
                    createdAt: '2026-07-16T13:20:48.559Z'
                    updatedAt: '2026-07-16T13:20:48.559Z'
                - id: july-2024
                  type: listedRealEstateReports
                  attributes:
                    name: July 2024
                    status: PROCESSING
                    createdAt: '2026-07-16T13:20:48.564Z'
                    updatedAt: '2026-07-16T13:20:48.564Z'
                meta:
                  totalCount: 2
                  itemCount: 5
                  pageCount: 1
                  currentPage: 1
                  prevPage: null
                  nextPage: null
                  lastPage: 1
                  fromRecord: 1
                  toRecord: 2
                links:
                  self: /insights/v0/listed_real_estate_reports?page=1&pageSize=5
                  prev: null
                  next: null
              schema:
                $ref: '#/components/schemas/json_api'
        '404':
          description: when requesting an overflow page
          content:
            application/vnd.api+json:
              example:
                errors:
                - status: '404'
                  title: Not Found
                  detail: 'The page requested was not found

                    The last page available is 1

                    '
              schema:
                $ref: '#/components/schemas/json_api'
        '403':
          description: unauthorized request
          content:
            application/vnd.api+json:
              example:
                errors:
                - status: '403'
                  title: Forbidden
                  detail: 'A valid auth token is required.

                    POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.

                    '
              schema:
                $ref: '#/components/schemas/json_api'
  /insights/v0/listed_real_estate_reports/{id}:
    get:
      summary: Retrieves an existing listed real estate report
      description: 'Provides access to the data for the listed real estate report.

        '
      tags:
      - Listed Real Estate Reports
      security:
      - OAuth2: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Listed Real Estate Report has been processed successfully
          content:
            application/vnd.api+json:
              example:
                data:
                  id: july-2023
                  type: listedRealEstateReports
                  attributes:
                    name: July 2023
                    status: PROCESSING
                    createdAt: '2026-07-16T13:20:49.145Z'
                    updatedAt: '2026-07-16T13:20:49.145Z'
              schema:
                $ref: '#/components/schemas/json_api'
        '404':
          description: Name is not found
          content:
            application/vnd.api+json:
              example:
                errors:
                - status: '404'
                  title: Not Found
                  detail: Page not found
              schema:
                $ref: '#/components/schemas/json_api'
        '403':
          description: when authenticated but not authorized
          examples:
            application/vnd.api+json:
              errors:
              - status: '403'
                title: Forbidden
                detail: Access Denied
          content:
            application/vnd.api+json:
              example:
                errors:
                - status: '403'
                  title: Forbidden
                  detail: Access Denied
              schema:
                $ref: '#/components/schemas/json_api'
components:
  schemas:
    success:
      type: object
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/data'
        included:
          description: To reduce the number of HTTP requests, servers **MAY** allow responses that include related resources along with the requested primary resources. Such responses are called 'compound documents'.
          type: array
          items:
            $ref: '#/components/schemas/resource'
          uniqueItems: true
        meta:
          $ref: '#/components/schemas/meta'
        links:
          description: Link members related to the primary data.
          allOf:
          - $ref: '#/components/schemas/links'
          - $ref: '#/components/schemas/pagination'
        jsonapi:
          $ref: '#/components/schemas/jsonapi'
      additionalProperties: false
    relationshipToOne:
      description: References to other resource objects in a to-one ('relationship'). Relationships can be specified by including a member in a resource's links object.
      anyOf:
      - $ref: '#/components/schemas/empty'
      - $ref: '#/components/schemas/linkage'
    relationshipLinks:
      description: A resource object **MAY** contain references to other resource objects ('relationships'). Relationships may be to-one or to-many. Relationships can be specified by including a member in a resource's links object.
      type: object
      properties:
        self:
          $ref: '#/components/schemas/link'
        related:
          $ref: '#/components/schemas/link'
      additionalProperties: true
    relationshipToMany:
      description: An array of objects each containing 'type' and 'id' members for to-many relationships.
      type: array
      items:
        $ref: '#/components/schemas/linkage'
      uniqueItems: true
    data:
      description: The document's 'primary data' is a representation of the resource or collection of resources targeted by a request.
      anyOf:
      - $ref: '#/components/schemas/resource'
      - description: An array of resource objects, an array of resource identifier objects, or an empty array ([]), for requests that target resource collections.
        type: array
        items:
          $ref: '#/components/schemas/resource'
        uniqueItems: true
      - description: null if the request is one that might correspond to a single resource, but doesn't currently.
    pagination:
      type: object
      properties:
        first:
          description: The first page of data
          type: string
          format: uri-reference
          x-nullable: true
        last:
          description: The last page of data
          type: string
          format: uri-reference
          x-nullable: true
        prev:
          description: The previous page of data
          type: string
          format: uri-reference
          x-nullable: true
        next:
          description: The next page of data
          type: string
          format: uri-reference
          x-nullable: true
    meta:
      description: Non-standard meta-information that can not be represented as an attribute or relationship.
      type: object
      additionalProperties: true
    failure:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
          uniqueItems: true
        meta:
          $ref: '#/components/schemas/meta'
        jsonapi:
          $ref: '#/components/schemas/jsonapi'
        links:
          $ref: '#/components/schemas/links'
      additionalProperties: false
    json_api:
      oneOf:
      - $ref: '#/components/schemas/success'
      - $ref: '#/components/schemas/failure'
      - $ref: '#/components/schemas/info'
    link:
      description: 'A link **MUST** be represented as either: a string containing the link''s URL or a link object.'
      oneOf:
      - description: A string containing the link's URL.
        type:
        - string
        - 'null'
        format: uri-reference
      - type: object
        required:
        - href
        properties:
          href:
            description: A string containing the link's URL.
            type: string
            format: uri-reference
          meta:
            $ref: '#/components/schemas/meta'
    links:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/link'
    empty:
      description: Describes an empty to-one relationship.
    linkage:
      description: The 'type' and 'id' to non-empty members.
      type: object
      required:
      - type
      - id
      properties:
        type:
          type: string
        id:
          type: string
        meta:
          $ref: '#/components/schemas/meta'
      additionalProperties: false
    error:
      type: object
      properties:
        id:
          description: A unique identifier for this particular occurrence of the problem.
          type: string
        links:
          $ref: '#/components/schemas/links'
        status:
          description: The HTTP status code applicable to this problem, expressed as a string value.
          type: string
        code:
          description: An application-specific error code, expressed as a string value.
          type: string
        title:
          description: A short, human-readable summary of the problem. It **SHOULD NOT** change from occurrence to occurrence of the problem, except for purposes of localization.
          type: string
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          type: string
        source:
          type: object
          properties:
            pointer:
              description: A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. '/data' for a primary data object, or '/data/attributes/title' for a specific attribute].
              type: string
            parameter:
              description: A string indicating which query parameter caused the error.
              type: string
        meta:
          $ref: '#/components/schemas/meta'
      additionalProperties: false
    jsonapi:
      description: An object describing the server's implementation
      type: object
      properties:
        version:
          type: string
        meta:
          $ref: '#/components/schemas/meta'
      additionalProperties: false
    attributes:
      description: Members of the attributes object ('attributes') represent information about the resource object in which it's defined.
      type: object
      additionalProperties: true
    info:
      type: object
      required:
      - meta
      properties:
        meta:
          $ref: '#/components/schemas/meta'
        links:
          $ref: '#/components/schemas/links'
        jsonapi:
          $ref: '#/components/schemas/jsonapi'
      additionalProperties: false
    relationships:
      description: Members of the relationships object ('relationships') represent references from the resource object in which it's defined to other resource objects.
      type: object
      properties:
        links:
          $ref: '#/components/schemas/relationshipLinks'
        data:
          description: Member, whose value represents 'resource linkage'.
          oneOf:
          - $ref: '#/components/schemas/relationshipToOne'
          - $ref: '#/components/schemas/relationshipToMany'
        meta:
          $ref: '#/components/schemas/meta'
      additionalProperties: true
    resource:
      description: '''Resource objects'' appear in a JSON:API document to represent resources.'
      type: object
      required:
      - type
      - id
      properties:
        type:
          type: string
        id:
          type: string
        attributes:
          $ref: '#/components/schemas/attributes'
        relationships:
          $ref: '#/components/schemas/relationships'
        links:
          $ref: '#/components/schemas/links'
        meta:
          $ref: '#/components/schemas/meta'
      additionalProperties: false
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.measurabl.com/token
          scopes: {}