IPera Starling | Developer Hub

# Location Information

# Get Location List

By using this API endpoint, it is possible to get list of locations that are created under a Tenant. Tenant represents customer and Locations represent their venues / branches / stores / physical locations.

# Endpoint

GET /locations

Rate Limit

This endpoint has a rate limit of 60 requests per minute.

# Parameters

Name Type Description
name string Filter by location name (performs text search)
status integer Filter by status (0: Active, 1: Trashed). If status=1, returns trashed locations
page integer Page number to be returned
per_page integer The number of records returned. Default is 10, maximum is 100

# Response

TIP

HTTP/1.1 200 OK

{
    "data": [
      {
        "id": "ZV4NljAPlq5",
        "name": "Costa Jeddah Street",
        "description": "",
        "login_page_name": "Prelogin (Live)",
        "login_page_id": "MmOPgO4P26x",
        "post_login_page_name": "Postlogin (Live)",
        "post_login_page_id": "elka5Y9aBn2",
        "is_trashed": false
      }
    ],

    "links": {
      "first": "[[BaseUrl]]/locations?page=1",
      "last": null,
      "prev": null,
      "next": "[[BaseUrl]]/locations?page=2"
    },

    "meta": {
      "current_page": 1,
      "from": 1,
      "path": "[[BaseUrl]]/locations",
      "per_page": 10,
      "to": 1
    }
}

# Get Location Count

By using this API endpoint, it is possible to get the count of the locations that are created under a Tenant.

# Endpoint

GET /locations/count

Rate Limit

This endpoint has a rate limit of 60 requests per minute.

# Parameters

Name Type Description
name string Filter by location name (performs text search)
status integer Filter by status (0: Active, 1: Trashed). If status=1, returns trashed locations

# Response

TIP

HTTP/1.1 200 OK

{
  "count": 1000
}

# Get Location Hierarchy

By using this API endpoint, it is possible to get list of location hierarchy. Api endpoint returns width and height data as meter.

# Endpoint

GET /locations/hierarchy

Rate Limit

This endpoint has a rate limit of 60 requests per minute.

# Parameters

Name Type Description
location_id string Filter by specific location ID
name string Filter by location name (performs text search)
with_coordinates integer Include coordinates in zone data. 1: Include, 0: Exclude (default)
scale_floor_dimensions integer Scale floor dimensions if grid count exceeds 3000. 1: Scale, 0: Don't scale (default)

# Response

TIP

HTTP/1.1 200 OK

{
    "data": [
      {
        "id": "ZV4NljAPlq5",
        "name": "West Location",
        "lat": "24.5013014",
        "lng": "54.3897024",
        "buildings" : [
          {
            "id": "TV5NYkjLq8",
            "name": "West Building",
            "lat": "41",
            "lng": "29",
            "floors": [
              {
                "id": "pXYG90jQnzk",
                "name": "West Floor F1",
                "image": {
                  "name": "[[BaseUrl]]/a/18_JdQRLpk6WGk/img/maps/Tmsöfdösn4sdfsfdsfsd.png",
                  "width": 5000,
                  "height": 3200
                },
                "dimensions": {
                  "width": 200,
                  "length": 200
                },
                "zones": [] 
              },
              {
                "id": "gep9lKOma16",
                "name": "West Floor F2",
                "image": {
                  "name": "[[BaseUrl]]/a/14_KLFDnldt5W9/img/maps/Kkjndfskfksbsdf.png",
                  "width": 4500,
                  "height": 3600
                },
                "dimensions": {
                  "width": 220,
                  "length": 192
                },
                "zones": [
                  {
                    "id": "Gvk9ZeDmPrV",
                    "name": "West Zone Z1"
                  }
                ] 
              }          
            ]  
          }
        ]
      }
    ]
}

# Create Location

Create a new location with given attributes.

# Endpoint

POST /locations

Rate Limit

This endpoint has a rate limit of 60 requests per minute.

# Parameters

Name Type Required Description
name string ✔ Name of the location. Max 50 characters. Must be unique for the tenant.
country_code string Country code. ISO 3166-1 alpha-2 country code.
city string City of the location.
address string Address of the location. Max 255 characters.
post_code string Post code of the location.
description string Description.
lat float Latitude coordinate
lng float Longitude coordinate
smart_login integer Smart login enabled or not. null: Inherit, 0: Disabled, 1: Enabled.
smart_login_frequency integer Smart login frequency. Required if smart_login=1. Min. 1
smart_login_frequency_type integer Smart login frequency unit. Required if smart_login=1. 2: Hours, 3: Days

# Response

TIP

HTTP/1.1 201 Created

{
  "data": {
    "id": "ZOpo383vB8X",
    "name": "Convert Venue",
    "description": "Optional description.",
    "address": "115 East 23rd Street 5th Floor",
    "post_code": "84500",
    "city": "Dubai",
    "state": null,
    "country_code": "AE",
    "lat": 25.6428852,
    "lng": 55.1966358,
    "is_trashed": false
  }
}

Unprocessable Entity

HTTP/1.1 422 Unprocessable Entity

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name field is required."
    ],
    "country_code": [
      "The country code field is invalid. It must be ISO 3166-1 alpha-2 country code."
    ]
  }
}

# Update Location

Update location information.

# Endpoint

PUT /locations/:id

Rate Limit

This endpoint has a rate limit of 60 requests per minute.

# Parameters

Name Type Required Description
:id string ✔ Location ID
name string ✔ Name of the location. Max 50 characters. Must be unique for the tenant.
country_code string Country code. ISO 3166-1 alpha-2 country code.
city string City of the location.
address string Address of the location. Max 255 characters.
post_code string Post code of the location.
description string Description.
lat float Latitude coordinate
lng float Longitude coordinate
smart_login integer Smart login enabled or not. null: Inherit, 0: Disabled, 1: Enabled.
smart_login_frequency integer Smart login frequency. Required if smart_login=1. Min. 1
smart_login_frequency_type integer Smart login frequency unit. Required if smart_login=1. 2: Hours, 3: Days

# Response

TIP

HTTP/1.1 200 OK

{
  "data": {
    "id": "ZOpo383vB8X",
    "name": "Convert Venue",
    "description": "Optional description.",
    "address": "115 East 23rd Street 5th Floor",
    "post_code": "84500",
    "city": "Dubai",
    "state": null,
    "country_code": "AE",
    "lat": 25.6428852,
    "lng": 55.1966358,
    "is_trashed": false
  }
}

Unprocessable Entity

HTTP/1.1 422 Unprocessable Entity

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name field is required."
    ],
    "country_code": [
      "The country code field is invalid. It must be ISO 3166-1 alpha-2 country code."
    ]
  }
}
Last Updated: 12/8/2025, 11:36:55 AM

← Location Analytics →