SightMap® REST API (v1.20220316)

Download OpenAPI specification:Download

Introduction

The SightMap® API uses standard HTTP verbs to communicate and HTTP status codes to indicate status and errors. All responses come in standard JSON. The SightMap API is served over HTTPS to ensure data privacy; HTTP is not supported.

Versioning

Versions are communicated as VERSION.RELEASE-DATE, where VERSION denotes the version number of the API and prefixed to all API request paths, such as /v1/assets. RELEASE-DATE denotes backwards-compatible changes to the API.

When any non-backwards compatible additions must be made to the API, the version number will be incremented.

Backwards-compatible changes

We consider the following changes to be backwards-compatible:

  • Adding new API resources.
  • Adding new optional request parameters to existing API methods.
  • Adding new properties to existing API responses.
  • Changing the order of properties in existing API responses.
  • Changing the length or format of object IDs or other opaque strings.
  • You can safely assume object IDs we generate will never exceed 255 characters, but you should be able to handle IDs of up to that length. If for example you’re using MySQL, you should store IDs in a VARCHAR(255) COLLATE utf8_bin column (the COLLATE configuration ensures case-sensitivity in lookups).

Authentication

For requests which require Authentication, an API Key can be provided by either the api-key query parameter or API-Key header. We recommend the header over the query parameter as it avoids your API key from being stored in browser history and most server logs. If neither query parameter or header is provided, a 401 status code is returned with the following JSON:

{
  "message": "No API key found in request"
}

If your API key cannot be validated, a 403 status code is returned with the following JSON:

{
  "message": "Invalid authentication credentials"
}

API Key

An API key sent via the API-Key header.

curl -i -H "API-Key: 12345" https://api.sightmap.com/v1/assets
Security Scheme Type API Key
Header parameter name: API-Key

Experimental features

We provide new API features via experimental flags. This allows users to opt-in for new functionality and provide feedback prior to a feature becoming generally available (GA). We believe in stability without stagnation. This ability allows our team to build and ship best-in-class APIs faster while upholding backwards-compatibility on GA features.

Experimental features are subject to change while undergoing development and feedback. Therefore, they are exempt from any backwards-compatibility guarantees until they reach GA. We do not expect nor recommend using experimental features in production environments unless a partnership has been established with our teams working closely together.

Flags are provided via the Experimental-Flags header. A comma-separated list is expected in order to pass multiple flags on a single request.

curl -i https://api.sightmap.com/v1/assets \
  -H "API-Key: 12345" \
  -H "Experimental-Flags: flag-1,flag-2"

Errors

The SightMap API uses standard HTTP status codes to indicate the success or failure of the API request. The body of the response will be JSON in the following format:

{
  "message": "Not found"
}

Accounts

List accounts

Returns a list of accounts.

Authorizations:
query Parameters
page
integer <int32>

Request a specific page of resources.

per-page
integer <int32>

Limit the number of returned resources.

Responses

Response samples

Content type
application/json
{
  • "paging": {
    },
  • "data": [
    ]
}

View an account

Returns a specific account.

Authorizations:
path Parameters
account
required
string <id> <= 255 characters

An account ID.

Responses

Response samples

Content type
application/json
{
  • "id": "95",
  • "name": "Engrain",
  • "created_at": "2017-09-11T17:09:18+00:00",
  • "updated_at": "2017-09-11T17:09:18+00:00"
}

Embeds

List embeds

Returns a list of embeds for an account.

Requires sightmap.embeds.read permission.

NOTICE: This resource is experimental and requires the embed-resource experimental flag.

Authorizations:
path Parameters
account
required
string <id> <= 255 characters

An account ID.

query Parameters
page
integer <int32>

Request a specific page of resources.

per-page
integer <int32>

Limit the number of returned resources.

asset
string <id> <= 255 characters

An asset ID to filter the list on.

header Parameters
Experimental-Flags
required
string

This resource is experimental and requires the embed-resource experimental flag.

Responses

Response samples

Content type
application/json
{
  • "paging": {
    },
  • "data": [
    ]
}

View an embed

Returns a specific embed.

Requires sightmap.embeds.read permission.

NOTICE: This resource is experimental and requires the embed-resource experimental flag.

Authorizations:
path Parameters
account
required
string <id> <= 255 characters

An account ID.

embed
required
string <id> <= 255 characters

An embed ID.

header Parameters
Experimental-Flags
required
string

This resource is experimental and requires the embed-resource experimental flag.

Responses

Response samples

Content type
application/json
{
  • "id": "5587",
  • "account_id": "95",
  • "name": "The Lofts at New Main",
  • "sightmaps": [
    ],
  • "created_at": "2020-10-30T15:16:35+00:00",
  • "updated_at": "2020-11-04T23:45:31+00:00"
}

Assets

List assets

Returns a list of allowed assets.

Authorizations:
query Parameters
page
integer <int32>

Request a specific page of resources.

per-page
integer <int32>

Limit the number of returned resources.

Responses

Response samples

Content type
application/json
{
  • "paging": {
    },
  • "data": [
    ]
}

Create an asset

Requires sightmap.assets.create permission

Authorizations:
Request Body schema: application/json
market
required
string
Enum: "affordable_housing" "agriculture" "airplane" "airport" "build_to_rent" "camping" "cemetery" "condos" "coworking" "cruise_ship" "cultural" "data_center" "demo" "education" "entertainment" "gallery_museum" "geography" "government" "harbor_marina" "healthcare" "hospitality" "industrial" "infrastructure" "land" "logistics" "manufactured_housing" "master_planned" "military_housing" "mixed_use" "multifamily" "office" "oil_and_gas" "other" "parking" "rentable_items" "resort" "retail" "salon" "self_storage" "senior_living" "single_family" "spa" "stadium_arena" "student" "theme_park" "transit"
name
required
string <= 255 characters
display_name
required
string <= 255 characters
description
string or null <= 255 characters
address_line1
required
string <= 63 characters
address_line2
string or null <= 63 characters
address_city
required
string <= 63 characters
address_state
required
string 2 characters

Two letter abbreviated state or province.

address_country
required
string 3 characters

An ISO 3166-1 alpha-3 country code.

address_postal_code
required
string <= 15 characters
address_latitude
number or null <float> [ -90 .. 90 ]
address_longitude
number or null <float> [ -180 .. 180 ]

Responses

Request samples

Content type
application/json
{
  • "market": "multifamily",
  • "name": "The Lofts at New Main",
  • "display_name": "The Lofts at New Main",
  • "description": null,
  • "address_line1": "100 New Main St",
  • "address_line2": null,
  • "address_city": "Cleveland",
  • "address_state": "OH",
  • "address_country": "USA",
  • "address_postal_code": "91801",
  • "address_latitude": 41.433243,
  • "address_longitude": -81.3941872
}

Response samples

Content type
application/json
{
  • "id": "1323",
  • "uuid": "d5779fbb-43fe-4d54-b642-266ce815a3f3",
  • "market": "multifamily",
  • "name": "The Lofts at New Main",
  • "display_name": "The Lofts at New Main",
  • "description": null,
  • "unit_count": 138,