# The Entity API

The Entity API is provided free of charge by Helium. The data provided focuses on infrequently changing attributes of Hotspots such as their owner and asserted location. This API is provided without any guarantees of uptime or support, and is intended for light use cases. For more in-depth analysis, refer to [Oracles](https://docs.helium.com/network-data/oracle-data) and [Solana on-chain data](https://docs.helium.com/network-data/solana-data).

In the interest of anonymity, the latitude/longitude data provided by the API is obfuscated to [H3](https://h3geo.org/docs/core-library/restable/) resolution 8 rather than resolution 12 stored on-chain on Solana.

## Active/Inactive Status

Active or Inactive status is deprecated for this API and will return `false` for all Hotspots on all routes.

## Wallet Info by Wallet Public Key

```text
GET https://entities.nft.helium.io/v2/wallet/:walletPublicKey
```

Get wallet information by wallet public key including Hotspot count, list of Hotspot records, and token account balances.

- Request
- Response

`Path Parameters`

| Param | Type | Note |
| --- | --- | --- |
| Wallet public key (required) | _string_ | Solana public key/address for the wallet |

`200: OK`

```json
{
  "hotspots_count": 1,
  "hotspots": [
    {
      "name": "string",
      "description": "string",
      "image": "string",
      "asset_id": "string",
      "key_to_asset_key": "string",
      "entity_key_b64": "string",
      "key_serialization": "string",
      "entity_key_str": "string",
      "hotspot_infos": {
        "iot": {
          "address": "string",
          "street": "string",
          "city": "string",
          "state": "string",
          "country": "string",
          "is_active": "boolean",
          "location": "string",
          "dc_onboarding_fee_paid": "string",
          "elevation": 0,
          "gain": 0,
          "created_at": "string",
          "asset": "string",
          "lat": 0,
          "long": 0
        },
        "mobile": {
          "location": null
        }
      },
      "attributes": [
        {
          "trait_type": "ecc_compact",
          "value": "string"
        },
        {
          "trait_type": "entity_key_string",
          "value": "string"
        },
        {
          "trait_type": "entity_key",
          "value": "string"
        },
        {
          "trait_type": "rewardable",
          "value": "boolean"
        },
        {
          "trait_type": "networks",
          "value": ["string"]
        },
        {
          "trait_type": "iot_city",
          "value": "string"
        },
        {
          "trait_type": "iot_state",
          "value": "string"
        },
        {
          "trait_type": "iot_country",
          "value": "string"
        },
        {
          "trait_type": "iot_lat",
          "value": 0
        },
        {
          "trait_type": "iot_long",
          "value": 0
        }
      ]
    }
  ],
  "balances": [
    {
      "mint": "hntyVP6YFm1Hg25TN9WGLqM12b8TQmcknKrdu1oxWux",
      "balance": "0"
    },
    {
      "mint": "mb1eu7TzEc71KxDpsmsKoucSSuuoGLv1drys1oP2jh6",
      "balance": "0"
    },
    {
      "mint": "iotEVVZLEywoTn1QdwNPddxPWszn3zFhEot3MfL9fns",
      "balance": "0"
    },
    {
      "mint": "dcuc8Amr83Wz27ZkQ2K9NS6r8zRpf1J6cvArEBDZDmm",
      "balance": "0"
    }
  ]
}
```

`500: Error`

```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "string"
}
```

## Hotspot Pagination Metadata

```text
GET https://entities.nft.helium.io/v2/hotspots/pagination-metadata?subnetwork=<subnetwork>
```

Get general information about the pagination of Hotspots in a particular subnetwork including pagination page size, total number of Hotspots, and total number of pages.

- Request
- Response

`Query Parameters`

| Param | Type | Note |
| --- | --- | --- |
| Subnetwork (required) | _string_ | Name of subnetwork (iot, mobile, etc) |

`200: OK`

```json
{
  "pageSize": 0,
  "totalItems": 0,
  "totalPages": 0
}
```

`400: Error`

```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "string"
}
```

`500: Error`

```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "string"
}
```

## List Hotspots by Subnetwork

```text
GET https://entities.nft.helium.io/v2/hotspots?subnetwork=<subnetwork>&cursor=<cursor>
```

Get a list of key-value pairs denoting Hotspots in a particular subnetwork. If the returned `cursor` field is a non-null value, more results are available. If no cursor is provided, then the first page of results is returned along with a cursor value for the subsequent page.

- Request
- Response

`Query Parameters`

| Param | Type | Note |
| --- | --- | --- |
| Subnetwork (required) | _string_ | Name of subnetwork (iot, mobile, etc.) |
| Cursor (optional) | _string_ | Cursor for the next page of Hotspots to fetch |

`200: OK`

```json
{
  "cursor": "string",
  "items": [
    {
      "key_to_asset_key": "string",
      "entity_key_str": "string",
      "is_active": "boolean",
      "lat": 0,
      "long": 0
    }
  ]
}
```

`400: Error`

```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "string"
}
```

`500: Error`

```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "string"
}
```

## Hotspot Info by Key to Asset Key

```text
GET https://entities.nft.helium.io/v1/:keyToAssetKey
```

```text
GET https://entities.nft.helium.io/v2/hotspot/:keyToAssetKey
```

Get Hotspot records based on the key to asset value. Both the `/v1` and `/v2/hotspot` routes return identical results and are merely provided for backward compatibility.

- Request
- Response

`Path Parameters`

| Param | Type | Note |
| --- | --- | --- |
| Key to asset (required) | _string_ | Public key of on-chain `KeyToAssetV0` struct |

`200: OK`

```json
{
  "name": "string",
  "description": "string",
  "image": "string",
  "asset_id": "string",
  "key_to_asset_key": "string",
  "entity_key_b64": "string",
  "key_serialization": "string",
  "entity_key_str": "string",
  "hotspot_infos": {
    "iot": {
      "address": "string",
      "street": "string",
      "city": "string",
      "state": "string",
      "country": "string",
      "is_active": "boolean",
      "location": "string",
      "dc_onboarding_fee_paid": "string",
      "elevation": 0,
      "gain": 0,
      "created_at": "string",
      "asset": "string",
      "lat": 0,
      "long": 0
    },
    "mobile": {
      "location": null
    }
  },
  "attributes": [
    {
      "trait_type": "ecc_compact",
      "value": "string"
    },
    {
      "trait_type": "entity_key_string",
      "value": "string"
    },
    {
      "trait_type": "entity_key",
      "value": "string"
    },
    {
      "trait_type": "rewardable",
      "value": "boolean"
    },
    {
      "trait_type": "networks",
      "value": ["string"]
    },
    {
      "trait_type": "iot_city",
      "value": "string"
    },
    {
      "trait_type": "iot_state",
      "value": "string"
    },
    {
      "trait_type": "iot_country",
      "value": "string"
    },
    {
      "trait_type": "iot_lat",
      "value": 0
    },
    {
      "trait_type": "iot_long",
      "value": 0
    }
  ]
}
```

`404: Error`

```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "string"
}
```

`500: Error`

```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "string"
}
```

## Hotspot Info by Entity/ECC Compact Key

```text
GET https://entities.nft.helium.io/:eccCompact
```

Get Hotspot records based on the entity / ECC compact key value.

- Request
- Response

`Path Parameters`

| Param | Type | Note |
| --- | --- | --- |
| Entity / ECC compact key | _string_ | Legacy Helium L1 address of the Hotspot |

`200: OK`

`404: Error`

```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "string"
}
```

`500: Error`

```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "string"
}
```

## List OUI Organization Info

```text
GET https://entities.nft.helium.io/v2/oui/all
```

Get a list of OUIs registered on the Helium Network and corresponding organization info.

- Response

`200: OK`

```json
{
  "orgs": [
    {
      "oui": 1,
      "owner": "string",
      "payer": "string",
      "escrow": "string",
      "delegate_keys": [
        "string"
      ],
      "locked": "boolean"
    },
    {
      "oui": 2,
      "owner": "string",
      "payer": "string",
      "escrow": "string",
      "delegate_keys": ["string"],
      "locked": "boolean"
    },
    {
      "oui": 3,
      "owner": "string",
      "payer": "string",
      "escrow": "string",
      "delegate_keys": ["string"],
      "locked": "boolean"
    }
  ]
}
```

`500: Error`

```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "string"
}
```

## OUI Organization Info by OUI ID

```text
GET https://entities.nft.helium.io/v2/oui/:id
```

Get an OUI registered on the Helium Network and corresponding organization info by the OUI ID.

- Request
- Response

`Path Parameters`

| Param | Type | Note |
| --- | --- | --- |
| OUI ID (required) | _string_ | ID of the OUI (e.g., 1) for getting info |

`200: OK`

```json
{
  "oui": 1,
  "owner": "string",
  "payer": "string",
  "escrow": "string",
  "delegate_keys": [
    "string"
  ],
  "locked": "boolean"
}
```

`400: Error`

```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "string"
}
```

`500: Error`

```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "string"
}
```