Index

Retrieve a list of all countries by making this request:

GET /api/v1/countries

Countries are paginated and can be iterated through by passing along a page parameter:

GET /api/v1/countries?page=2

Parameters

page
The page number of country to display.
per_page
The number of countries to return per page

Response

Status: 200 OK
{
  "countries": [
    {
      "id": 1,
      "iso_name": "UNITED STATES",
      "iso": "US",
      "iso3": "USA",
      "name": "United States",
      "numcode": 1,
      "states": [
        {
          "state": {
            "abbr": "NY",
            "country_id": 1,
            "id": 1,
            "name": "New York"
          }
        }
      ]
    }
  ],
  "count": 25,
  "pages": 5,
  "current_page": 1
}

To search for a particular country, make a request like this:

GET /api/v1/countries?q[name_cont]=united

The searching API is provided through the Ransack gem which Spree depends on. The name_cont here is called a predicate, and you can learn more about them by reading about Predicates on the Ransack wiki.

The search results are paginated.

Response

Status: 200 OK
{
  "countries": [
    {
      "id": 1,
      "iso_name": "UNITED STATES",
      "iso": "US",
      "iso3": "USA",
      "name": "United States",
      "numcode": 1,
      "states": [
        {
          "state": {
            "abbr": "NY",
            "country_id": 1,
            "id": 1,
            "name": "New York"
          }
        }
      ]
    }
  ],
  "count": 25,
  "pages": 5,
  "current_page": 1
}

Results can be returned in a specific order by specifying which field to sort by when making a request.

GET /api/v1/countries?q[s]=name%20desc

Show

Retrieve details about a particular country:

GET /api/v1/countries/1

Response

Status: 200 OK
{
  "id": 1,
  "iso_name": "UNITED STATES",
  "iso": "US",
  "iso3": "USA",
  "name": "United States",
  "numcode": 1,
  "states": [
    {
      "state": {
        "abbr": "NY",
        "country_id": 1,
        "id": 1,
        "name": "New York"
      }
    }
  ]
}