Overview

This documentation provides information about the rest api for Snapcloud. This is a location based service, and provides information about countries, states, towns and local governments. It also provides boundary information about them. It also provides advanced features such as ability to fetch addresses and streets, as well as check in to them.;

HTTP verbs

This RESTful API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

PUT

Used to update an existing resource, including partial updates

DELETE

Used to delete an existing resource

HTTP status codes

This RESTful API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

204 No Content

An update to an existing resource has been applied successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

404 Not Found

The requested resource did not exist

Resources

Countries

Get all countries

A GET request will get all of the countries.

Response structure

Path Type Description

[]

Array

List of countries

[].name

String

Name of the country

[].code

String

Code/abbreviation for the country

Example request

$ curl 'https://snapcloudv2-dev.shoppi.ng/api/v1/public/countries' -i -H 'Content-Type: application/json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 57

[ {
  "id" : 1,
  "name" : "Nigeria",
  "code" : "NG"
} ]

Get a country by id

A GET request will get a country.

Request structure

Table 1. /api/v1/public/countries/id/{id}
Parameter Description

id

The id of the country

Response structure

Path Type Description

name

String

Name of the country

code

String

Code/abbreviation for the country

id

Number

id of the country

Example request

$ curl 'https://snapcloudv2-dev.shoppi.ng/api/v1/public/countries/id/1' -i -H 'Content-Type: application/json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 53

{
  "id" : 1,
  "name" : "Nigeria",
  "code" : "NG"
}

Get a country by name or code

A GET request will get a country by name or code.

Request structure

Table 2. /api/v1/public/countries/{name_or_code}
Parameter Description

name_or_code

The name or code of the country

Response structure

Path Type Description

name

String

Name of the country

code

String

Code/abbreviation for the country

id

Number

id of the country

Example request

$ curl 'https://snapcloudv2-dev.shoppi.ng/api/v1/public/countries/Nigeria' -i -H 'Content-Type: application/json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 53

{
  "id" : 1,
  "name" : "Nigeria",
  "code" : "NG"
}

Regions

Get all Regions

A GET request will get all of the regions for a country.

Request structure

Table 3. /api/v1/public/country/{countryId}/regions
Parameter Description

countryId

The id of the country

Response structure

Path Type Description

[]

Array

List of regions

[].id

Number

id of the region

[].name

String

Name of the region

[].code

String

Code/abbreviation for the region

Example request

$ curl 'https://snapcloudv2-dev.shoppi.ng/api/v1/public/country/1/regions' -i -H 'Content-Type: application/json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 63

[ {
  "id" : 1,
  "name" : "North Central",
  "code" : "NC"
} ]

Get a region by id

A GET request will get a region by id.

Request structure

Table 4. /api/v1/public/regions/{id}
Parameter Description

id

The id of the region

Response structure

Path Type Description

name

String

Name of the region

code

String

Code/abbreviation for the region

id

Number

id of the region

Example request

$ curl 'https://snapcloudv2-dev.shoppi.ng/api/v1/public/regions/1' -i -H 'Content-Type: application/json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 59

{
  "id" : 1,
  "name" : "North Central",
  "code" : "NC"
}

Get a region by name

A GET request will get a region by name.

Request structure

Table 5. /api/v1/public/country/{countryId}/region/{name}
Parameter Description

name

The name of the region

countryId

The id of the country

Response structure

Path Type Description

name

String

Name of the region

code

String

Code/abbreviation for the region

id

Number

id of the region

Example request

$ curl 'https://snapcloudv2-dev.shoppi.ng/api/v1/public/country/1/region/North%20Central' -i -H 'Content-Type: application/json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 59

{
  "id" : 1,
  "name" : "North Central",
  "code" : "NC"
}

Get a region by code

A GET request will get a region by code.

Request structure

Table 6. /api/v1/public/country/{countryId}/region/code/{code}
Parameter Description

code

The name of the region

countryId

The id of the country

Response structure

Path Type Description

name

String

Name of the region

code

String

Code/abbreviation for the region

id

Number

id of the region

Example request

$ curl 'https://snapcloudv2-dev.shoppi.ng/api/v1/public/country/1/region/code/NC' -i -H 'Content-Type: application/json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 59

{
  "id" : 1,
  "name" : "North Central",
  "code" : "NC"
}

States

Get all states for a country

A GET request will get all of the states in a country.

Request structure

Table 7. /api/v1/public/country/{countryId}/states
Parameter Description

countryId

The id of the country

Response structure

Path Type Description

[]

Array

List of states

[].id

Number

id of the state

[].name

String

Name of the state

[].code

String

Code/abbreviation for the state

[].capital

String

capital of the state

Example request

$ curl 'https://snapcloudv2-dev.shoppi.ng/api/v1/public/country/1/states' -i -H 'Content-Type: application/json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 103

[ {
  "id" : 7,
  "name" : "Benue",
  "code" : "Food Basket of the nation",
  "capital" : "Makurdi"
} ]

Get all states in a region

A GET request will get all of the states in a region.

Request structure

Table 8. /api/v1/public/region/{regionId}/states
Parameter Description

regionId

The id of the region

Response structure

Path Type Description

[]

Array

List of states

[].id

Number

id of the state

[].name

String

Name of the state

[].code

String

Code/abbreviation for the state

[].capital

String

capital of the state

Example request

$ curl 'https://snapcloudv2-dev.shoppi.ng/api/v1/public/region/1/states' -i -H 'Content-Type: application/json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 103

[ {
  "id" : 7,
  "name" : "Benue",
  "code" : "Food Basket of the nation",
  "capital" : "Makurdi"
} ]

Get a state by id

A GET request will get a state by id.

Request structure

Table 9. /api/v1/public/states/{id}
Parameter Description

id

The id of the state

Response structure

Path Type Description

id

Number

id of the state

name

String

Name of the state

code

String

Code/abbreviation for the state

capital

String

capital of the state

Example request

$ curl 'https://snapcloudv2-dev.shoppi.ng/api/v1/public/states/7' -i -H 'Content-Type: application/json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 99

{
  "id" : 7,
  "name" : "Benue",
  "code" : "Food Basket of the nation",
  "capital" : "Makurdi"
}

Get a state by name

A GET request will get a state by name.

Request structure

Table 10. /api/v1/public/country/{countryId}/state/{name}
Parameter Description

name

The name of the state

countryId

The id of the country

Response structure

Path Type Description

id

Number

id of the state

name

String

Name of the state

code

String

Code/abbreviation for the state

capital

String

capital of the state

Example request

$ curl 'https://snapcloudv2-dev.shoppi.ng/api/v1/public/country/1/state/Benue' -i -H 'Content-Type: application/json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 99

{
  "id" : 7,
  "name" : "Benue",
  "code" : "Food Basket of the nation",
  "capital" : "Makurdi"
}

Get a state by capital

A GET request will get a region by capital.

Request structure

Table 11. /api/v1/public/country/{countryId}/capital/{capital}
Parameter Description

capital

The capital of the state

countryId

The id of the country

Response structure

Path Type Description

id

Number

id of the state

name

String

Name of the state

code

String

Code/abbreviation for the state

capital

String

capital of the state

Example request

$ curl 'https://snapcloudv2-dev.shoppi.ng/api/v1/public/country/1/capital/Makurdi' -i -H 'Content-Type: application/json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 99

{
  "id" : 7,
  "name" : "Benue",
  "code" : "Food Basket of the nation",
  "capital" : "Makurdi"
}

Towns

Get all towns for a state

A GET request will get all of the towns in a state.

Request structure

Table 12. /api/v1/public/state/{stateId}/towns
Parameter Description

stateId

The id of the state

Response structure

Path Type Description

[]

Array

List of states

[].id

Number

id of the state

[].name

String

Name of the state

[].code

String

Code/abbreviation for the state

[].is_local_government

Boolean

Indicates whether a town is a local government

[].parent_town_id

Number

Indicates the parent id of the town

Example request

$ curl 'https://snapcloudv2-dev.shoppi.ng/api/v1/public/state/7/towns' -i -H 'Content-Type: application/json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 232

[ {
  "id" : 1831,
  "name" : "Agatu",
  "code" : "Agatu",
  "is_local_government" : true,
  "parent_town_id" : 0
}, {
  "id" : 1950,
  "name" : "Gboko",
  "code" : "Gboko",
  "is_local_government" : true,
  "parent_town_id" : 0
} ]

Get all local governments in a state

A GET request will get all of the local governments in a state.

Request structure

Table 13. /api/v1/public/state/{stateId}/local_governments
Parameter Description

stateId

The id of the state

Response structure

Path Type Description

[]

Array

List of states

[].id

Number

id of the state

[].name

String

Name of the state

[].code

String

Code/abbreviation for the state

[].is_local_government

Boolean

Indicates whether a town is a local government

[].parent_town_id

Number

Indicates the parent id of the town

Example request

$ curl 'https://snapcloudv2-dev.shoppi.ng/api/v1/public/state/7/local_governments' -i -H 'Content-Type: application/json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 232

[ {
  "id" : 1831,
  "name" : "Agatu",
  "code" : "Agatu",
  "is_local_government" : true,
  "parent_town_id" : 0
}, {
  "id" : 1950,
  "name" : "Gboko",
  "code" : "Gboko",
  "is_local_government" : true,
  "parent_town_id" : 0
} ]

Get a town by id

A GET request will get a town by id.

Request structure

Table 14. /api/v1/public/towns/{id}
Parameter Description

id

The id of the town

Response structure

Path Type Description

id

Number

id of the state

name

String

Name of the state

code

String

Code/abbreviation for the state

is_local_government

Boolean

Indicates whether a town is a local government

parent_town_id

Number

Indicates the parent id of the town

Example request

$ curl 'https://snapcloudv2-dev.shoppi.ng/api/v1/public/towns/1831' -i -H 'Content-Type: application/json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 113

{
  "id" : 1831,
  "name" : "Agatu",
  "code" : "Agatu",
  "is_local_government" : true,
  "parent_town_id" : 0
}