API Documentation

External parties can acces information about industrial and office buildings, including property details, location information, pricing, and availability. This API makes it easy for external parties to streamline their processes and access the data they need to provide their customers with up-to-date information about properties all over the world.

The Urbanum API is a REST API accessible through HTTPs. All endpoints return JSON-encoded responses and uses standard HTTP response codes and verbs.

Authentication

Authentication to the API is performed via the Authorization header.

i.e. Get buildings

curl https://api.urbanum.app/v1/buildings -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni..."

Resources

Refresh Token

Allows the user to exchange a valid refresh token for a new access token, which can be used to continue accessing the service.

Endpoint URL: https://api.urbanum.app/v1/auth/token/refresh

Request headers:

Content-Type: set to application/json

Request body:

The request body should contain a JSON object with the following field:

refresh_token (required): a string representing the user's refresh token.

Example request body:

 {
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response:

The API responds with a JSON object containing the access token and its expiration time:

access_token: a string representing the user's new access token, which can be used to authenticate future requests.
expires_in: an integer representing the number of seconds until the access token expires.

Example response body:

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 3600
}

Possible response status codes:

200 OK: The request was successful, and the new access token is included in the response body.
400 Bad Request: The request body is missing or invalid.
401 Unauthorized: The provided refresh token is invalid or has expired.
500 Internal Server Error: An unexpected error occurred on the server.

Retrieve Buildings

Endpoint URL: https://api.urbanum.app/v1/buildings

This endpoint retrieves a list of active buildings in the platform.

Parameters:

page (optional): The maximum number of buildings to return per request. If not provided, a default value is used.
market_id (optional): The market identifier of the buildings to search for

Example request

curl https://api.urbanum.app/buildings -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Example response

{
	"current_page": 1,
  "count": 9123,
  "previous": null,
  "total_pages": 457,
  "page_size": 20,
  "next": "https://api.urbanum.app/v1/buildings?page=2",
  "results": [
    {
      "token_id": "47917",
      "name": "902 Hornet Way",
      "building_type": "industrial",
      "year_built": 2018,
      "location": {
        "lat": 33.92429530236272,
        "lng": -118.38010767243841
      },
      "address": "902 Hornet Way, El Segundo, California 90245, United States",
      "rentable_area": 90534.67095135504,
      "available_area": 0,
			"street_number": "902",
			"street_name": "Hornet Way",
			"city": "El Segundo",
			"state": "California",
			"country": "United States",
			"zipcode": "90245",
			"market": "Los Angeles Industrial",
			"submarket": "Downtown Los Angeles",
			"developer_name": null,
			"status": "existing",
			"rating": "4",
			"attributes": {
        "min_clear_height": 20,
        "building_use": "Warehouse",
        "dock_high_doors": 4,
        "drive_in_doors": 2,
        "sprinklers": true,
        "rating": "4",
        "parking_non_trailer": 50,
        "tenancy": "Single",
        "lot_size": 100000,
        "walls": "Concrete",
        "power": "400 Amps",
        "office_area": 5000,
        "rail_spur": false,
        "skylights": true,
        "hvac": "Central",
        "sustainability": "LEED Certified",
        "parking_trailer": 20,
        "developer_name": null,
        "column_spacing": 40
			}
    }
    ...
  ]
}

Fields

current_page: The page number of the current page of results.
count: The total number of buildings available in the database.
previous: The URL of the previous page of results. This will be null if the current page is the first page.
total_pages: The total number of pages of results available, based on the page_size parameter.
page_size: The maximum number of buildings returned per page.
next: The URL of the next page of results. This will be null if the current page is the last page.
results: An array of building objects containing the following fields:
- token_id: A unique identifier for the building.
- name: The name of the building.
- building_type: The type of the building, such as office or industrial
- year_built: The year in which the building was constructed.
- location: An object containing the latitude and longitude coordinates of the building.
- address: The street address of the building.
- rentable_area: The total area of the building that can be rented out.
- available_area: The area of the building that is currently available for rent.
- street_number: The number component of the street address.
- street_name: The name component of the street address.
- city: The city in which the building is located.
- state: The state in which the building is located.
- country: The country in which the building is located.
- zipcode: The zip code of the building.
- market: The real estate market in which the building is located.
- submarket: The submarket within the real estate market in which the building is located.
- developer_name: The name of the developer who constructed the building.
- status: The current status of the building, such as "existing" or "under construction".
- rating: A rating for the building, such as a star rating or a numerical rating.
If the building type is industrial, additional attributes are included under the key attributes:
- min_clear_height: The minimum clear height of the building.
- building_use: The designated use of the building.
- dock_high_doors: The number of dock high doors available in the building.
- drive_in_doors: The number of drive-in doors in the building.
- sprinklers: Indicates whether the building is equipped with sprinklers.
- rating: The rating assigned to the building.
- parking_non_trailer: The number of parking spaces available for vehicles that are not trailers.
- tenancy: Describes the occupancy status or arrangement of tenants in the building.
- lot_size: The size of the lot or land on which the building is situated.
- walls: Specifies the type of walls used in the construction of the building.
- power: Refers to the power capacity or electrical supply available in the building.
- office_area: The total area designated for office space within the building.
- rail_spur: Indicates whether the building has a rail spur.
- skylights: Indicates whether the building has skylights.
- hvac: Describes the heating, ventilation, and air conditioning system in the building.
- sustainability: Indicates the level of sustainability features or certifications of the building.
- parking_trailer: The number of parking spaces available for trailers.
- developer_name: The name of the developer associated with the building.
- column_spacing: The spacing between columns in the building.
If the building type is office the response should include the following attributes:
- office_floors: The number of floors designated for office space in the building.
- avg_floor_size: The average size of each office floor in the building.
- ceiling_height: The height of the ceilings in the office spaces.
- parking_ratio: The ratio of parking spaces to the total office area.
- parking_spots: The total number of parking spots available for office occupants.
- sprinklers : Indicates whether the office spaces are equipped with sprinkler systems for fire protection.
- hvac: Describes the heating, ventilation, and air conditioning system in the office spaces.
- sustainability: Indicates the level of sustainability features or certifications of the office building.
Retrieve Listings

This endpoint retrieves a list of active listings in the platform.

Parameters:
- page (optional): The maximum number of buildings to return per request. If not provided, a default value is used.
- sort_by (optional): The field by which the buildings should be sorted. Possible values include price, size, location, and so on. If not provided, a default sorting order is used. TBD
Example request
```
curl https://api.urbanum.app/listings -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```
Example response
```
{
	"current_page": 1,
  "count": 9123,
  "previous": null,
  "total_pages": 457,
  "page_size": 20,
  "next": "https://api.urbanum.app/v1/listings?page=2",
  "results": [
    {
			"id": 6473,
      "token_id": "47917",
			"building": 
        {
				"id": 74893	
				"name": "902 Hornet Way",
				"address": "902 Hornet Way, El Segundo, California 90245, United States",
				},
      "size": 25000.00,
      "minimum_divisible": 500.00,
			"operation": "rent|sale",
			"price": 12.50,
			"lease_type": "fsg|mg|n|nn|nnn",
			"description": ".....",
			"sublease": true,
			"price_scheme": "unit_month|total_month|unit_year",
      "agents":
        {
          "company": "CBRE",
          "email": "michael.smith@cbre.com",
          "first_name": "Michael",
          "last_name": "Smith",
          "phone": 3105758951
        },
        {
          "company": "CBRE",
          "email": "michael.smith@cbre.com",
          "first_name": "Michael",
          "last_name": "Smith",
          "phone": 3105758951
        },
    },
			....
  ]
}
```
Retrieve Markets

This endpoint retrieves the list of markets available in our platform

Parameters:
- page (optional): The maximum number of buildings to return per request. If not provided, a default value is used.
- sort_by (optional): The field by which the buildings should be sorted. Possible values include price, size, location, and so on. If not provided, a default sorting order is used. TBD
Example request
```
curl https://api.urbanum.app/v1/markets -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```
Example response

Fields:
- current_page: The page number of the current page of results.
- count: The total number of listings available in the database.
- previous: The URL of the previous page of results. This will be null if the current page is the first page.
- total_pages: The total number of pages of results available, based on the page_size parameter.
- page_size: The maximum number of listings returned per page.
- next: The URL of the next page of results. This will be null if the current page is the last page.
- results: An array of listing objects containing the following fields:
  - id: A unique identifier for the listing.
  - token_id: A unique BC identifier for the listing.
  - building: An object containing the following fields related to the building associated with the listing:
    - id: A unique identifier for the building.
    - name: The name of the building.
    - address: The street address of the building.
  - size: The size of the listing in square meters.
  - minimum_divisible: The minimum divisible unit of the listing in square meters.
  - operation: The type of operation for the listing, either "rent" or "sale".
  - price: The price of the listing, if the operation is "rent", or the total sale price of the listing, if the operation is "sale".
  - lease_type: The type of lease for the listing, if the operation is "rent". Possible values include "FSG" (full-service gross), "MG" (modified gross), "N" (net), "NN" (double net), and "NNN" (triple net).
  - description: A description of the listing.
  - sublease: A boolean indicating whether the listing is a sublease or not.
  - price_scheme: The pricing scheme used in the market, such as unit/month, total/month, or unit/year.
```
{
	"current_page": 1,
  "count": 300,
  "previous": null,
  "total_pages": 15,
  "page_size": 20,
  "next": "https://api.urbanum.app/v1/markets?page=2",
  "results": [
    {
			"id": 1,
      "token_id": "20",
			"name": "San Diego Industrial",
			"country": "United States of America",
			"type": "building|office",
			"currency": "USD",
			"price_scheme": "unit_month|total_month|unit_year",
			"units": "m|ft",
			"rent_period": "month|year",
			"geometry": { "type": "Polygon", "coordinates": [ [ [ -118.380226, 33.554118 ], [ -116.579596, 33.873948 ], [ -115.972246, 32.597958 ], [ -117.302323, 32.531216 ], [ -118.380226, 33.554118 ] ] ] }
			"area": "San Diego"
    },
			....
  ]
}
```
  Fields
  - current_page: The current page of results returned in the response.
  - count: The total number of markets available in the database.
  - previous: The URL for the previous page of results. If the current page is the first page, this value will be null.
  - total_pages: The total number of pages of results available.
  - page_size: The number of markets returned per page.
  - next: The URL for the next page of results. If the current page is the last page, this value will be null.
  - results: An array containing the individual market objects returned in the response.
  For each market object in the results array, the following fields are included:
  - id: A unique identifier for the market.
  - token_id: A token identifier for the market.
  - name: The name of the market.
  - country: The country in which the market is located.
  - type: The type of market, whether it's for building or office.
  - currency: The currency used for pricing in the market.
  - price_scheme: The pricing scheme used in the market, such as unit/month, total/month, or unit/year.
  - units: The units of measurement used in the market, whether they're meters or feet.
  - rent_period: The period for which rent is charged, whether it's by month or year.
  - geometry: The polygon that defines the geographic boundaries of the market.
  - area: The name of the region or area covered by the market.
  Market Reports
  
  Deliver insights and data regarding real estate markets on a monthly basis. It allows users to stay informed about market trends, fluctuations in average property prices, and the performance of different market types (office or industrial). Users can utilize this information for decision-making processes such as investment strategies, property evaluations, and market analysis.
  
  Endpoint URL: https://api.urbanum.app/v1/reports/monthly-markets
  
  HTTP method: GET
  
  Response:
  
  The API responds with a JSON object containing the following fields for each market included in the monthly report:
  - market_name: The name of the market.
  - country: The country in which the market is located.
  - date: The date of the report.
  - average_price: The average price of real estate properties in the market for the specified month.
  - net_change: The net change in average price compared to the previous month.
  - change_percentage: The percentage change in average price compared to the previous month.
  - market_type: The type of market, indicating whether it is for office or industrial real estate.
  - id: A unique identifier for the market.
  - token_id: A token identifier for the market.
  - units: The units used for measuring the listings in the market, whether it's square feet (ft) or meters (m).
  Example response body:
```
[
        {
            "market_name": "San Diego Industrial",
            "country": "United States of America",
            "date": "2023-04-01",
            "average_price": 15.25,
            "net_change": -0.75,
            "change_percentage": -4.69,
            "market_type": "industrial",
            "id": 1,
            "token_id": "20",
            "units": "ft"
        },
        {
            "market_name": "Paris Office",
            "country": "France",
            "date": "2023-04-01",
            "average_price": 520,
            "net_change": 23,
            "change_percentage": 4.2,
            "market_type": "office",
            "id": 2,
            "token_id": "25",
            "units": "m"
        },
        ...
]
``
```

API Documentation

Authentication

Resources

Refresh Token

Retrieve Buildings

Fields

Retrieve Listings

Retrieve Markets

Fields:

Fields

Market Reports