Skip to main content Skip to main navigation Skip to footer

API Reference

Connect Your Website to DotSquare

The DotSquare API is a PHP only service at this point in time. JSON is returned by all API responses, including errors.


Your API version is directly linked to the version of DotSquare that you are running so be mindful of this when upgrading dotSquare. You will need to FTP and initialize the DotSquare API on your web server each time you update to ensure everything functions properly.

API Library

The official dotSquare library is only available in PHP (version 5.6 or higher).

API EndPoint

https://cms.fiveonedevelopment.com/dotsquare/{API-VERSION}/api/

Authentication

Connect your account by including your DotSquare API key in API requests. You can find your DotSquare API key inside DotSquare. Then visit "Developers" → "Account". When connecting to DotSquare, your API key will also be set.

Example Request

\DotSquare\Initialize::connect({API-KEY});

Setting a New API Key

If you have multiple partitions, each partition has it's own API key. Be sure to use the key that correlates to desired partition. You can reset the API Key for the partition you need by simply calling setApiKey().

Example Request

\DotSquare\DotSquare::setApiKey('ds_HerEub8YjMvGOQmdGf0z');
// New key will now be used for all following requests

The Response Object

All DotSquare API responses output JSON objects.


Attributes

success
boolean
Has the value true if the the call returned no errors.
message
string
Returns a front end friendly message.
http_code
integer
Returns the HTTP code of the the response.
data
list
This is the heart of the response. All relevant data will be listed here. This list will be empty if an error is found.
error
list
The error data, if any.
  → type
    string
The error type. All possible error types are listed in the "Errors" section.
  → debug
    string
Outputs a string with more details on the error for development purposes.
Example Request

\DotSquare\Geo::getUSZipData([
  'us_zip'=>'92101'
]);
Example Response

DotSquare\Geo JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'city': 'San Diego',
    'state': 'US-CA',
    'lat': 32.726967,
    'lng': -117.164709
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Errors

DotSquare uses conventional HTTP response codes to indicates the status of an API request result.


Codes in the 500+ are indicative of a dotSquare error.

HTTP Status Codes

200 - OK
Everything worked as expected.
400 - Bad Request
The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized
No valid API key provided.
402 - Request Failed
The parameters were valid but the request failed.
404 - Not Found
Not Found The requested resource doesn't exist.
409 - Conflict
The request conflicts with another request (perhaps due to using the same idempotent key)
429 - Too Many Requests
Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors
Something went wrong on DotSquare's end.
DotSquare Error Types
api_connection_error
Failure to connect to DotSquare's API.
api_error
API errors cover any other type of problem (e.g., a temporary problem with DotSquare's servers).
authentication_error
Failure to properly authenticate in the request.
idempotency_error
Idempotency errors occur when an Idempotency-Key is re-used on a request that does not match the first request's API endpoint and parameters.
invalid_request_error
Invalid request errors arise when your request has invalid parameters.
rate_limit_error
Too many requests ran through the DotSquare API too quickly.

Handing Errors

DotSquare API returns an array of information including elemnt containing success or failure or the call. You can test the "success" key for a true value to determine the status of the result.


If an error is thrown, you can display further error details inside the "error" array.

Example Request

$response = \DotSquare\Geo::getUSZipData([
	'us_zip'=>'92101'
]);
Example Response - Error Handing

if($response->success){
	// Do Something ...
} else {
	$type = $response->error->type;
	$debug = $response->error->debug;
}

Initialize

The first connection to DotSquare

This is the first thing that must be done when setting up a dotSquare website if not using our Framework. The DotSquare Framework natively handles this operation in the init.php file.


Arguments

key
Required
The API key provided by DotSquare
Example Request

\DotSquare\Initialize::connect({API-KEY});
Example Response

DotSquare\Initialize JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'database': {
      'host': 'fiveonedevelopment.com',
      'user': 'myUsername',
      'pass': 'myPassword',
      'client_db': 'my_db_name',
      'client_db_ecomm': 'my_db_name_ecomm',
      'db_connection_id': 2,
      'db_token': 'db_XXXXXXXXXXXXXX',
    }, 
    'account': {
      'ecommerce': true,
      'tier': 'multi_partition',
    },
    'paths': {
      'ds_path': 'dotsquare/6.60.0/',
      'base_url': '/',
      'upload_root_path': 'https://cms.fiveonedevelopment.com/',
      'upload_base_url': 'https://cms.fiveonedevelopment.com/',
      'ds_root_path': 'https://cms.fiveonedevelopment.com/',
      'ds_base_url': 'https://cms.fiveonedevelopment.com/',
      'gs_base_url': 'https://api.go-spotter.com/'
    }, 
    'UTC_timestamp': 1714091012,
    'UTC_offset': -8,
    'webspace': 'demoWebspace',
    'ds_version': '6.60.0',
    'cache_token': 'F5TRDKXwvO2MthyzpQ6r',
    'partition_id': 1,
    'custom_id': 1,
    'salt': 'SsWPMPcWkw4BoWXh6AOe',
    'cookie_prefix': 'demowebspace-XXXXX';
    'time_zone': 'America/Los_Angeles',
    'live_mode': true
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Data

Request Social Media, Custom Fields, and more

Use this API class to easily retrieve curated data from our servers.

Social Data

Returns data about a social website or app. This is useful when formatting icons and querying our database for listed social websites. For more information about social media data visit the Resource Guide


Arguments

social_id
optional
The dotSquare ID of the social media network or website. The social_id can be found by querying the database.

Data Attributes

site
string
The name of the website or app.
domain
string
The domain of the social website.
icon_name
string
The vector icon code name (svg file). All icons have a naming pattern of {STYLE-ID}{ICON-NAME}1.svg.
Ex. 4fb1.svg.

The "Style ID" determines the look such as a circle around the logo or a solid square.
Example Request

\DotSquare\Data::getSocialData([
  'social_id' => 1
]);
Example Response

DotSquare\Data JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
      1: {
        'site_name': 'Facebook',
        'domain': 'Facebook.com',
        'icon_name': 'fb',
      }    
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Custom Fields

DotSquare allows custom fields objects such as Staff, FAQS, etc. This is useful if you need very specific information about an object to be stored. For more information about custom fields visit the Resource Guide

Returns data about all fields used in your website.


Data Attributes

fields
list
List of all data
  → type_title
    string
A user friendly short decription of what this field is.
  → type
    string
The field type.
Ex. int, varchar, decimal, text, binary, datetime.
  → max_length
    int
The maximum characters the field can reach.
  → max_value
    int
The maximum amount that the field can reach.
Example Request

\DotSquare\Data::getFieldsData();
Example Response

DotSquare\Data JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'num_fields': 3,
    'fields': {
      0: {
        'type_title': 'Short Text',
        'type': 'varchar',
        'max_length': null,
        'max_value': null,
      }
      1: /* DotSquare Data */,
      2: /* DotSquare Data */
    },
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Edit Mode

In addition to editing website text directly through the dashboard app, in certain cases, DotSquare also allows admins to change app text (displayed on the website) in edit mode. This can make it more intuitive for admins to edit their website. This is natively included in the DotSquare Framework so no extra coding is required unless you wish to create custom features.

An example is if staff is listed with descriptions and titles. With this API, the bio and title for each staff member can be changed in edit mode.


Learn more about DotSqaure's Page Editor App


Arguments

col_id
Required
The ID of the edit mode reference. A full list of IDs can be found in the Reference Guide

Data Attributes

table_name
string
The name of the table dotSquare pulls from
row_target_name
string
The column name that is used to search the instance of the value specified. Think of this as the x-axis. Usually id.
col_target_name
string
The column name that is used for this data type. Think of this as the y-axis.
plain_text
boolean
Details whether or not the value returned is HTML or Plain Text.
max_length
int
If the field has a max length, specifies the number of characters.
Example Request

\DotSquare\Data::getEditModeData([
  'col_id' => 1
]);
Example Response

DotSquare\Data JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'table_name': 'cms_staff',
    'row_target_name': 'id',
    'col_target_name': 'title',
    'plain_text': false,
    'max_length': null,
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Organization

Request Information Relevant to the Organization

Use this API class to easily retrieve information about an organizations service areas.

Service Areas

DotSquare allows you to store where a business or organization does business. This is useful in delivery businesses, organizations that have exclusive operations within a geography and more.

You can retrieve all service areas or retrieve a selected service area.


Arguments

location_id
optional
Request data only from a certain location id.
category_id
optional
Request data only from a certain category id.
select_by
optional
Specify if you wish to find a specific service area
Ex. coordinates, zip_code, city, county
select_attributes
optional assoc. array
The arguments to enter if select_by is specified.
  → lat
    required [1]
Specify the latitude to find results around coordinates. Must be used with the lng argument.
  → lng
    required [1]
Specify the longitude to find results around coordinates. Must be used with the lat argument.
  → distance
    optional
Specify the distance in miles around coordinates. Can only be used with the lat and lng arguments. Defaults to 100 miles if no argument is specified.
  → zip_code
    required [2]
The zip code to search for.
  → city
    required [3]
The city name to search for. May return multiple cities if there are multiple cities with the same name. Specify the state to return a unique city.
  → county
    required [4]
The county name to search for. May return multiple counties if there are multiple counties with the same name. Specify the state to return a unique county.
  → state
    optional
The full state name to search for (ex. California). If used in conjunction with city or county, this attribute will be used for filtering the city and county.
order_by
optional
All values are ordered Ascending. Order by distance can only be used with the select_by: coordinates argument.
Ex. distance, zip_code, city, county, state.
limit
optional
The maximum number of results returned. Default is 100.

Data Attributes

num_rows
int
Number of results found
rows
list
List of all data
  → zip_code
    string
The 5 digit US zip code
  → city
    string
Full city name
  → county
    string
Full county name
  → state
    string
Full US state name
  → distance
    string
Distance away from coordinates specified in miles. Maximum distance returned is 100 miles.
Example Request

\DotSquare\Org::getServiceAreas([
  'select_by' => 'coordinates',
  'select_arributes' => [
    'lng'=>32.7211000000,
    'lat'=>-117.1743660000
  ],
  'order_by'=>'distance',
  'limit'=>40
]);
Example Response

DotSquare\Org JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'num_rows': 40,
    'rows': {
      0: {
        'zip_code': '92101',
        'city': 'San Diego',
        'county': 'San Diego',
        'state': 'California',
        'lng': 32.7211000000,
        'lat': -117.1743660000,
        'distance': 0.1,
      },
      1: /* DotSquare Data */,
      2: /* DotSquare Data */
    },
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}