Skip to content
Roamex API

List regions

POST
/regions
curl --request POST \
  --url 'https://api.roamex.com/v1/regions?lang=nl' \
  --header 'Authorization: Bearer <token>'

Lists the countries and regions that have plans you can buy, regions first. Pass a slug as region to /plans; planCount is the number of plans it returns for that slug. The request body is ignored.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
lang
string
default: en

Language of plan and destination names in the response: en, nl, es, de, it, fr, pl, pt, tr, el, cs or ro. Any other value, or none, gives English. It never changes which items are returned or any figure.

Example 

nl

Responses

Section titled “Responses”

200

Section titled “200”

Every country and region with plans.

Media typeapplication/json
object
success
required
boolean
regions
required

Regions first, by plan count from high to low, then countries by name.

Array<object>
object
slug
required

Pass as region to /plans. A country’s slug is its lower-case country code.

string
name
required
string
type
required
string
Allowed values: country region
countries
required

Country codes.

Array<string>
countryNames
required
Array<string>
planCount
required

The number of plans /plans returns for this slug.

integer
total
required

Number of entries in regions.

integer

Example 

{
  "success": true,
  "regions": [
    {
      "slug": "europe",
      "name": "Europe (30 countries)",
      "type": "region",
      "countries": [
        "AT",
        "BE",
        "DE"
      ],
      "countryNames": [
        "Austria",
        "Belgium",
        "Germany"
      ],
      "planCount": 42
    },
    {
      "slug": "jp",
      "name": "Japan",
      "type": "country",
      "countries": [
        "JP"
      ],
      "countryNames": [
        "Japan"
      ],
      "planCount": 27
    }
  ],
  "total": 2
}

Headers

Section titled “Headers”
X-RateLimit-Limit
integer

Calls allowed per minute for this endpoint group.

X-RateLimit-Remaining
integer

Calls left in the current minute.

X-RateLimit-Reset
integer

When the current window ends, in Unix seconds.

401

Section titled “401”

AUTH_ERROR: the key is missing, malformed, unknown or revoked. The message says which, for example Missing Authorization header, Invalid Authorization header format. Use: Bearer <api_key>, Invalid API key format or Invalid API key.

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false,
  "error": {
    "code": "AUTH_ERROR",
    "message": "Invalid API key"
  }
}

403

Section titled “403”

AUTH_ERROR: the account is suspended (Your account is suspended. Please contact support.) or rejected (Account is not approved for API access).

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false
}

404

Section titled “404”

NOT_FOUND: the API is switched off on the platform. Every endpoint answers this before the key is checked, with the message This feature is not available.

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "This feature is not available."
  }
}

413

Section titled “413”

PAYLOAD_TOO_LARGE: the Content-Length header is over 100 KB.

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false
}

429

Section titled “429”

RATE_LIMITED: the account’s per-minute budget for this endpoint group is used up, or too many refused keys came from this IP address. Wait the Retry-After seconds.

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please wait 42 seconds before retrying."
  }
}

Headers

Section titled “Headers”
X-RateLimit-Limit
integer

Calls allowed per minute for this endpoint group.

X-RateLimit-Remaining
integer

Calls left in the current minute.

X-RateLimit-Reset
integer

When the current window ends, in Unix seconds.

Retry-After
integer

Seconds to wait before retrying.

500

Section titled “500”
  • INTERNAL_ERROR: an unexpected error on our side.
  • AUTH_ERROR with status 500: the key could not be checked because of an error on our side. Retry with backoff.
Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false
}

503

Section titled “503”

Transient. Retry with backoff.

  • PRICING_UNAVAILABLE: your account pricing could not be confirmed.
  • REGIONS_UNAVAILABLE: the region list could not be loaded.
Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false
}