Country Object

This section describes the elements of the Country object.

Country Object Attributes

These fields and values make up the JSON object that gets returned with successful requests.

Attribute	Data Type	Description
capital read only	string	The capital of the country.
common_name read only	string	The common name of the country.
dialing_prefix read only	string	The telephone code of the country.
domain read only	string	The Internet domain of the country.
iso_3166_alpha_2 read only	string	The ISO 3166-1 alpha-2 code of the country.
iso_3166_alpha_3 read only	string	The ISO 3166-1 alpha-3 code of the country.
iso_3166_numeric read only	integer	The ISO 3166-1 numeric code of the country.
mcc read only	string	The mobile country code.
official_name read only	string	The official name of the country.
region read only	string	The region of the country.
subregion read only	string	The subregion of the country.

Sample Country Object

{
    "capital": "Washington D.C.",
    "common_name": "United States",
    "dialing_prefix": "1",
    "domain": "us",
    "iso_3166_alpha_2": "US",
    "iso_3166_alpha_3": "USA",
    "iso_3166_numeric": 840,
    "mcc": "310,311,312,313,316",
    "official_name": "United States of America",
    "region": "Americas",
    "subregion": "Northern America"
}

Get Countries

This request returns a list of countries.

get	/countries

Sample

A sample GET request to get a list of countries:

curl -X GET \
'https://api.carrierx.com/core/v2/countries?limit=1' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response

200 status code with a list of Country objects:

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "capital": "Washington D.C.",
            "common_name": "United States",
            "dialing_prefix": "1",
            "domain": "us",
            "iso_3166_alpha_2": "US",
            "iso_3166_alpha_3": "USA",
            "iso_3166_numeric": 840,
            "mcc": "310,311,312,313,316",
            "official_name": "United States of America",
            "region": "Americas",
            "subregion": "Northern America"
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/countries?limit=1&offset=1"
    },
    "total": 249
}

This request is enabled for Pagination, Result Filtering, and Field Filtering.

Required Scopes

To get information about Country objects, the partner must have one of the following scopes enabled:

• countries.manage
• countries.read

Get Country by ISO Code

This request returns the country associated with an ISO 3166-1 alpha-3 code.

get	/countries/{country_code}

Sample

A sample GET request to get a country, targeted by ISO code (with the common name excluded):

curl -X GET \
'https://api.carrierx.com/core/v2/countries/ITA?exclude_fields=common_name' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response

200 status code with a serialized copy of the Country object:

{
    "capital": "Rome",
    "dialing_prefix": "39",
    "domain": "it",
    "iso_3166_alpha_2": "IT",
    "iso_3166_alpha_3": "ITA",
    "iso_3166_numeric": 380,
    "mcc": "222",
    "official_name": "Italian Republic",
    "region": "Europe",
    "subregion": "Southern Europe"
}

This request is enabled for Field Filtering.

Required Scopes

To get information about a Country object, the partner must have one of the following scopes enabled:

• countries.manage
• countries.read

Path Arguments

Parameter	Data Type	Description
country_code required	string	The ISO 3166-1 alpha-3 code of the country.

Get Country by IP Address

This request returns the country associated with an IP address.

get	/countries/{ip_address}}

Sample

A sample GET request to get a country associated with an IP address:

curl -X GET \
'https://api.carrierx.com/core/v2/countries/ip/2.6.26.2' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response

200 status code with a serialized copy of the Country object:

{
    "city": "Bordeaux",
    "common_name": "France",
    "iso_3166_alpha_2": "FR",
    "region": "Nouvelle-Aquitaine",
    "state": null
}

tip

Contact technical support at support@carrierx.com to enable searching for countries by IP address.

Required Scopes

To get information about a Country object, the partner must have one of the following scopes enabled:

• countries.manage & lookup.ip_addresses.read
• countries.read & lookup.ip_addresses.read

Path Arguments

Parameter	Data Type	Description
ip_address required	string	The IPv4 address.