# eSIM API - Package(s)

> To get a list of eSIM packages, you need to send a GET request to the /api/esim/packages endpoint.

Canonical: https://docs.getroamify.com/esims/packages/

## Ways to get eSIM packages
To get a list of eSIM packages, you need to send a `GET` request to the `/api/esim/packages` endpoint. 

> **Warning:** Breaking change: `/api/esim/packages` now returns paginated results. If you do not pass `page` and `pageSize`, you may only receive the first page.

> **Warning:** `country` and `countryCode` now have different meanings. Both must use values returned from `GET /api/esim/countries`.

> **Warning:** Watch out property "withUsageCheck", if it is set to false, usage check won't be supported, find instructions in the notes property

> **Warning:** Watch out property "withThrottle", if it is set to true, throttling will in-effect, find more info in the throttle property

The request query can include the following parameters:
- `page`: Page number to retrieve. This is an optional field of type `string`. Default: `1`.
- `pageSize`: Number of results per page. This is an optional field of type `string`. Default: `50`.
- `country`: Full country name filter. This is an optional field of type `string`. Use the `name` value from `GET /api/esim/countries`.
- `countryCode`: ISO country code filter. This is an optional field of type `string`. Use the `code` value from `GET /api/esim/countries`.
- `geography`: The geography of the eSIM packages. This is an optional field of type `string`. It can be any of the following values:
  - `local`: Local packages
  - `regional`: Regional packages
  - `global`: Global packages
- `days`: The number of days for which the eSIM package is valid. This is an optional field of type `number`.
- `gbs`: The amount of data in GB for which the eSIM package is valid. This is an optional field of type `number`.
- `isUnlimited`: The flag to indicate if the eSIM package is unlimited. This is an optional field of type `boolean`.
- `packageId`: The ID of the eSIM package. This is an optional field of type `string`.

> **Note:** To fetch all packages, iterate pages until the current page returns fewer items than your `pageSize`.

## Usage examples
Here is an example of how you can get a list of eSIM packages using Roamify eSIM API.

### Example Request 1: Get first page of eSIM packages

**curl**

```bash
curl --request GET \
--url 'https://api-dev.getroamify.com/api/esim/packages?page=1&pageSize=50' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json'
```

**javascript**

```javascript
const axios = require('axios');

axios.get('https://api-dev.getroamify.com/api/esim/packages?page=1&pageSize=50', {
    headers: {
        'Authorization': 'Bearer {access token here}',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});
```

<br />
<br />

### Example Request 2: Filter by `country` (full country name)

**curl**

```bash
curl --request GET \
--url 'https://api-dev.getroamify.com/api/esim/packages?country=United%20States&page=1&pageSize=50' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json'
```

**javascript**

```javascript
const axios = require('axios');

axios.get('https://api-dev.getroamify.com/api/esim/packages?country=United%20States&page=1&pageSize=50', {
    headers: {
        'Authorization': 'Bearer {access token here}',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});
```

<br />

### Example Request 3: Filter by `countryCode` (ISO code)

**curl**

```bash
curl --request GET \
--url 'https://api-dev.getroamify.com/api/esim/packages?countryCode=US&page=1&pageSize=50' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json'
```

**javascript**

```javascript
const axios = require('axios');

axios.get('https://api-dev.getroamify.com/api/esim/packages?countryCode=US&page=1&pageSize=50', {
    headers: {
        'Authorization': 'Bearer {access token here}',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});
```

### Example Request 4: Get eSIM packages for a specific geography

**curl**

```bash
curl --request GET \
--url 'https://api-dev.getroamify.com/api/esim/packages?geography=global&page=1&pageSize=50' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json'
```

**javascript**

```javascript
const axios = require('axios');

axios.get('https://api-dev.getroamify.com/api/esim/packages?geography=global&page=1&pageSize=50', {
    headers: {
        'Authorization': 'Bearer {access token here}',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});
```

### Example Request 5: Get eSIM packages for specific days and GBs

**curl**

```bash
curl --request GET \
--url 'https://api-dev.getroamify.com/api/esim/packages?days=3&gbs=10&page=1&pageSize=50' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json'
```

**javascript**

```javascript
    const axios = require('axios');

    axios.get('https://api-dev.getroamify.com/api/esim/packages?days=3&gbs=10&page=1&pageSize=50', {
    headers: {
    'Authorization': 'Bearer {access token here}',
    'Content-Type': 'application/json'
}
})
    .then(response => {
    console.log(response.data);
})
    .catch(error => {
    console.error(error);
});
```

### Sample Response
```json
{
	"status": "success",
	"data": {
		"packages": [
			{
				"id": "afghanistan-esims",
				"countryName": "Afghanistan",
				"countryCode": "AF",
				"countrySlug": "afghanistan",
				"region": "Asia",
				"geography": "local",
				"minPrice": 5,
				"maxPrice": 5,
				"image": "https://imagedelivery.net/uUE6LNs_ci8SFBH4_n66dQ/countries/flags/afghanistan/public",
				"signals": [
					{
						"code": "AF",
						"name": "Afghanistan",
						"networks": [
							"3G",
							"4G"
						],
						"carriers": [
							"MTN"
						]
					}
				],
				"packages": [
					{
						"packageId": "esim-canada-15days-un2gb-all",
						"package": "Unlimited Data - 15 Days (2 GB / 128 KBPS)",
						"plan": "data-only",
						"activation": "first-use",
						"day": 15,
						"price": 1.32,
						"isUnlimited": true,
						"isAPNAutomatic": true,
						"apn": "drei.at",
						"dataAmount": 9007199254740991,
						"dataUnit": "MB",
						"callType": "all",
						"callAmount": -1,
						"callUnit": "",
						"smsType": "all",
						"smsAmount": -1,
						"smsUnit": "",
						"withSMS": false,
						"withCall": false,
						"withHotspot": true,
						"withDataRoaming": true,
						"withDestinationInstall": false,
						"withUsageCheck": true,
						"withThrottle": true,
						"throttle": {
							"throttleSpeed": 128,
							"throttleSpeedUnit": "kbps",
							"throttleThreshold": 2,
							"throttleThresholdUnit": "gb"
						},
						"notes": []
					}
				]
			}
        ]
    },
    "pagination": {
        "page": 1,
        "pageSize": 50,
        "totalItems": 2,
        "totalPages": 1,
        "hasNextPage": false,
        "hasPreviousPage": false
    }
}
```
