# Regions

The Region API endpoints provide a listing and detail for all of your defined entry/exit regions, including custom shapes (polygons) and circles (point/radius).


## Region listing {#getregions}

Get a paginated list regions. The result is an array of [Region objects](/docs/developer/rest-api/ua/schemas/regions/#regionobject) under the `"regions"` key.

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

### `GET /api/regions`

**Security:**

- [basicAuth]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-basicAuth)

**Query parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | `integer` |  | Determines the number of results per page. Defaults to 100, with a maximum of 1,000 regions per page. Setting a `limit` greater than 1,000 returns a 400 response. Max: 1000 |
| `start` | `integer` |  | A zero-based integer offset into the ordered list of regions, useful for addressing pages directly. |

**Responses**

**`200`** Returns OK for success.

Response body:

**Content-Type:** `application/vnd.urbanairship+json; version=3`

- **`count`** `integer`

  The total number of regions returned.

- **`next_page`** `string`

  There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results.

  Format: `url`

  Example: `https://go.urbanairship.com/api/regions?limit=100&start=100`

- **`ok`** `boolean`

  Success.

- **`regions`** `array` <[Region object]({{< ref "/developer/rest-api/ua/schemas/regions/" >}}#regionobject)>

  An array of region objects.

**`400`** Returned when `limit` is greater than 1,000.

Response body:

**Content-Type:** `application/vnd.urbanairship+json; version=3`

[Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error)

**`401`** Authentication information (the app key and secret or bearer token) was either incorrect or missing.

Response body:

**Content-Type:** `text/plain`

[Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error)

**`404`** The requested resource doesn't exist.

Response body:

**Content-Type:** `application/vnd.urbanairship+json`

[Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error)

**Examples**

*Example*

```http
GET /api/regions/?limit=100&start=100 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

```

```http
HTTP/1.1 200 OK
Data-Attribute: regions
Link: <https://go.urbanairship.com/api/regions?limit=100&start=100>; rel=next
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "next_page": "https://go.urbanairship.com/api/regions?limit=100&start=100",
   "count": 100,
   "regions": [
       {
           "region_id": "abe5deb3-01d0-436e-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": 120.0
                   },
                   {
                       "latitude": 45.0,
                       "longitude": 120.0
                   },
                   {
                       "latitude": 0.0,
                       "longitude": 0.0
                   }
               ]
           },
           "beacons": [
               {
                   "name": "entryway",
                   "id": "VLSHZAOEXOFCMLDVTKFQ"
               },
               {
                   "name": "Exhibit A",
                   "id": "ZAQYMNOZKRFCRPYEUCZI"
               }
           ],
           "attributes": {
               "store_name": "Tonali's Donuts"
           },
           "source_info": {
               "source": "GIMBAL",
               "region_id": "C56654BC0C3243D6A4B7A3673560D6F8",
               "vendor_href": "https://manager.gimbal.com/api/v2/places/C56654BC0C3243D6A4B7A3673560D6F8"
           }
       }
   ]
}

```

---

## Region lookup {#getregion}

Get details for a specific region.

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

### `GET /api/regions/{region_id}`

**Security:**

- [basicAuth]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-basicAuth)

**Path parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `region_id` | `string` | Required | The region you want to lookup. |

**Responses**

**`200`** Returns OK for success.

Response body:

**Content-Type:** `application/vnd.urbanairship+json; version=3`

- **`ok`** `boolean`

  If true, indicates success.

  Example: `true`

- **`region`** `object` <[Region object]({{< ref "/developer/rest-api/ua/schemas/regions/" >}}#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.

**`401`** Authentication information (the app key and secret or bearer token) was either incorrect or missing.

Response body:

**Content-Type:** `text/plain`

[Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error)

**`404`** The requested resource doesn't exist.

Response body:

**Content-Type:** `application/vnd.urbanairship+json`

[Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error)

**Examples**

*Example*

```http
GET /api/regions/7d4d9a5c-eff5-40f2-b648-4352c166e878 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

```

```http
HTTP/1.1 200 OK
Data-Attribute: region
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "region": {
        "region_id": "7dbd9a5c-eff5-40f2-b648-4352c1668878",
        "created_at": "2020-08-24T23:15:22.900",
        "updated_at": "2020-08-24T23:15:22.900",
        "name": "Alberta Park",
        "source_info": {
            "source": "GIMBAL",
            "region_id": "C56654BC0C3243D6A4B7A3673560D6F8",
            "vendor_href": "https://manager.gimbal.com/api/v2/places/C56654BC0C3243D6A4B7A3673560D6F8"
        },
        "geofence": {
            "type": "CIRCLE",
            "center": {
                "latitude": 45.56447530000002,
                "longitude": -122.64461097354126
            },
            "radius": 200
        },
        "attributes": {
             "park_name": "alberta",
             "type": "park"
        }
    }
}

```

---