Countries

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
    }
  ],
  "count": 25,
  "current_page": 1,
  "pages": 5
}

Search

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 Boxid 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
    }
  ],
  "count": 25,
  "current_page": 1,
  "pages": 5
}

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": [
    {
      "id": 1,
      "name": "New York",
      "abbr": "NY",
      "country_id": 1
    }
  ]
}

Edit this page on GitHub