# Regions

The following schemas represent ways to target by location, region, or geofence.


## Geofence object {#geofenceobject}

A Geofence object describes a geographical boundary corresponding to a physical location of relevance to the application or application owner. The geofence `type` can be a `polygon`, a `circle`, or provided by a `confidential` source.

[Jump to examples ↓](#geofenceobject-examples)

**One of:**

- **Polygon Geofence object** `object`

  A Geofence subtype describing a polygon.

  - **`points`** `array` <[Point object]({{< ref "/developer/rest-api/ua/schemas/regions/" >}}#pointobject)> **REQUIRED**

    An ordered array of Points that correspond to the vertices of the polygon on the globe.

  - **`type`** `string` **REQUIRED**

    The key `type` indicating a polygon geofence subtype.

    Possible values: `POLYGON`

- **Circle Geofence object** `object`

  A Geofence subtype describing a circle.

  - **`center`** `object` <[Point object]({{< ref "/developer/rest-api/ua/schemas/regions/" >}}#pointobject)> **REQUIRED**

    A single Point indicating the center fo the circle.

    A Point object is a simple JSON object corresponding to a point on the globe, consisting of only two keys: latitude and longitude.

  - **`radius`** `integer` **REQUIRED**

    An integer indicating the size (in meters) of the radius of the circle whose edge is the geofence boundary.

  - **`type`** `string` **REQUIRED**

    The key `type` indicating a circle geofence subtype.

    Possible values: `CIRCLE`

- **Confidential Geofence object** `object`

  A confidential Geofence subtype.

  - **`id`** `string` **REQUIRED**

    The source-specific identifier for this geofence.

  - **`source`** `string` **REQUIRED**

    The name of the company providing the geofence.

  - **`type`** `string` **REQUIRED**

    The key `type` indicating a confidential geofence subtype.

    Possible values: `CONFIDENTIAL`

  - **`version`** `string` **REQUIRED**

    The version number for the source of this geofence.


**Used in:**

- [Region listing]({{< ref "/developer/rest-api/ua/operations/regions/" >}}#getregions)
- [Region lookup]({{< ref "/developer/rest-api/ua/operations/regions/" >}}#getregion)

**Examples**

*Polygon Geofence*

```json
{
    "type": "POLYGON",
    "points": [
        {
            "latitude": 1.000,
            "longitude": 90
        },
        {
            "latitude": 2.000,
            "longitude": 90
        },
        {
            "latitude": 3.000,
            "longitude": 0
        }
    ]
}

```

*Circle Geofence*

```json
{
    "type": "CIRCLE",
    "center": {
        "latitude": 0,
        "longitude": 0
    },
    "radius": 1000
}

```

*Confidential Geofence*

```json
{
    "type": "CONFIDENTIAL",
    "source": "Maponics",
    "version": "1.0.17-BETA",
    "id": "TheLouvreMuseumFloodZoneParis"
}

```

---

## Point object {#pointobject}

A Point object is a simple JSON object corresponding to a point on the globe, consisting of only two keys: latitude and longitude.

[Jump to examples ↓](#pointobject-examples)

- **`latitude`** `number` **REQUIRED**

  Decimal with maximum 6 digits of decimal precision in the range [-90,90].

  Format: `float`

- **`longitude`** `number` **REQUIRED**

  Decimal with maximum 6 digits of decimal precision in the range of [0, 180)

  Format: `float`


**Used in:**

- [Region listing]({{< ref "/developer/rest-api/ua/operations/regions/" >}}#getregions)
- [Region lookup]({{< ref "/developer/rest-api/ua/operations/regions/" >}}#getregion)

**Examples**

*Coordinate point example*

```json
{
    "latitude": 45,
    "longitude": 179.999999
}

```

---

## Region object {#regionobject}

A Region object describes a geographical boundary or set of hardware identifiers and associated attributes that correspond to a physical location of relevance to the application or application owner.

[Jump to examples ↓](#regionobject-examples)

- **`attributes`** `object`

  An attribute object is an object containing the customer-provided region attributes associated with a particular region.

- **`beacons`** `array[object]`

  An array of beacon objects.

- **`created_at`** `string` **REQUIRED**

  The creation [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) for the region.

  Format: `date-time`

  Example: `2018-03-01T12:00:00`

- **`geofence`** `object` <[Geofence object]({{< ref "/developer/rest-api/ua/schemas/regions/" >}}#geofenceobject)>

  A Geofence object describes a geographical boundary corresponding to a physical location of relevance to the application or application owner. The geofence `type` can be a `polygon`, a `circle`, or provided by a `confidential` source.

- **`name`** `string`

  A human-readable name for the region.

  Example: `My Favorite Place`

- **`region_id`** `string` **REQUIRED**

  A string containing a UUID that is the canonical identifier for this object, elsewhere referred to as `region_id`.

  Format: `uuid`

  Example: `abe5deb3-00d0-446e-8c5d-94b6421a01e0`

- **`source_info`** `object`

  A Source Info object is a simple JSON object providing the details about the origin of the region data.

  **OBJECT PROPERTIES**

  - **`region_id`** `string` **REQUIRED**

    Internal identifier used by source for this region.

    Example: `4BPSFLKJSDFLKJSDFLKJ`

  - **`source`** `string` **REQUIRED**

    Name of the company who originated the region data.

    Example: `GIMBAL`

  - **`vendor_href`** `string`

    URI indicating the location of the original source of this region data.

    Example: `https://manager.gimbal.com/api/2/places/4BPSFLKJSDFLKJSDFLKJ`

- **`updated_at`** `string` **REQUIRED**

  The last updated [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) for the region.

  Format: `date-time`

  Example: `2018-03-01T12:00:00`


**Used in:**

- [Region listing]({{< ref "/developer/rest-api/ua/operations/regions/" >}}#getregions)
- [Region lookup]({{< ref "/developer/rest-api/ua/operations/regions/" >}}#getregion)

**Examples**

*Example polygon-type Geofence imported from Gimbal*

```json
{
    "region_id": "abe5deb3-00d0-446e-8c5d-94b6421a01e0",
    "name": "My Favorite Place",
    "created_at": "2020-06-09T12:34:56",
    "updated_at": "2020-06-09T12:34:56",
    "geofence": {
        "type": "POLYGON",
        "points": [
            {
                "latitude": 90.0,
                "longitude": 180.0
            },
            {
                "latitude": 90.0,
                "longitude": 180.0
            },
            {
                "latitude": 0.0,
                "longitude": 0.0
            }
        ]
    },
    "beacons": [
        {
            "name": "entryway",
            "id": "VLSHLAOEXOFCMLDVTKFQ"
        },
        {
            "name": "Exhibit A",
            "id": "ZAQQMNOZKRFCRPYEUCZI"
        }
    ],
    "attributes": {
        "store_name": "REI"
    },
    "source_info": {
        "source": "GIMBAL",
        "region_id": "4BPSFLKJSDFLKJSDFLKJ",
        "vendor_href": "http://api.gimbal.com/2/places/4BPSFLKJSDFLKJSDFLKJ"
    }
}

```

---