The Mapsimise API is organised around REST.
Our API has predictable resource-oriented URLs, accepts JSON request, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
All successful responses are returned as JSON. We wrap the returned data in our StatusResult model.
Status:int
1 - Operation was successful
Usually accompanied by the Data:object result.
0 - A process error occurred
We have detected an error with handling your request. See ResponseText:string for the reason.
-1 - An exception error occurred
Internal server error we were unable to handle fully. See ResponseText:string for for more details.
ResponseText:string
If an error has occurred we try to provide a human readable explanation of the error.
Data:object
This is the json object of your request, returned after your query has been completed successfully.
You may also receive an error 400 in situations where the client input cannot be parsed or does not match the required type.
In this case you will receive a standard HTTP 400 error object.
If we have managed to successfully receive the request but find errors the responseJSON will contain a StatusResult object for you to interrogate.
You will receive an error 500 if there was an unexpected error generated, this can happen for a number of reason.
We provide an error reference as part of the error message. If you continue receiving the error you can contact use with this refernce. This will help aid us in resolving the issue.
{
"Status": int,
"ResponseText": string,
"Data": object
}{
"readyState": 4,
"responseText": "{\"Status\":0,\"ResponseText\":\"Reason\"}",
"responseJSON": {
"Status": 0,
"ResponseText": "Reason"
},
"status": 400,
"statusText": "Bad Request"
}{
"readyState": 4,
"responseText": "{\"Message\":\"The request is invalid.\",\"MessageDetail\":\"Reason\"}",
"responseJSON": {
"Message": "The request is invalid.",
"MessageDetail": "Reason"
},
"status": 400,
"statusText": "Bad Request"
}In order to access the API you must provide an authorization key in the header of the HTTP request.
Your API Key is located in your user profile. Log in an click your initial icon, in the top right, then select 'Edit Profile'. At the bottom of your profile you can generate and/or copy your authorization key.
Your Mapsimise user permissions for accessing DataTable information will also apply to accessing the API.
Our API allows for the creation and updating of your DataTables. You can specify column types and the key field as well as configure the GeocodeRule to geocode your data.
Retrieve a list of your DataTables.
TableId:int
A GUID identifying your table.
DisplayName:string
A name given to your table for easier identification.
DateCreated:datetime
The date and time the table was create.
DateUpdated:datetime
The date and time the table had changes made to it.
{
"Status": int,
"ResponseText": string,
"Data": [
{
"TableId": string (GUID),
"DisplayName": string,
"DateCreated": datetime,
"DateUpdated": datetime,
}, ...
]
}Retrieve a single DataTables. In addition to the properties listed above, you are also provided with an array of Columns and the GeocodeRule
tableId:guid
The id of the DataTable.
Column:array
A List of Columns defining the DataTable.
GeocodeRule:dictionary
A dictionary representing the GeocodeRule.
{
"Status": int,
"ResponseText": string,
"Data": {
"TableId": guid,
"RowCount": int,
"DateCreated": datetime,
"DateUpdated": datetime,
"DisplayName": string,
"Columns": [
{
"DisplayName": string,
"FieldId": string,
"Type": int,
"PrimaryKey": bool
}, ...
],
"GeocodeRule": {
"AddressLine1": string,
"AddressLine2": string,
"AddressLine3": string,
"City": string,
"State": string,
"County": string,
"PostalCode": string,
"Country": string,
"DefaultCountry": string,
"Latitude": string,
"Longitude": string
}
}
}A table requires a DisplayName and at least 1 Column. You can also supply the GeocodeRule during the creation process.
DisplayName:string
A name given to your table for easier identification.
Column:array
A List of Columns defining the DataTable. At least 1 column is required.
FieldId:string
Name of the column. Only Alpha-Numeric and underscore (_) characters are permitted. Field names are cleared of any other characters before being created.
DisplayName:string
Optional name that will be displayed to end users.
Type:string
Defines the type of data to be stored in this column. See Type for a complete list of valid values.
PrimaryKey:boolean
If supplied this column will become the primary key for the table. This field is used to identify records when updating via the API.
GeocodeRule:dictionary
A dictionary representing the GeocodeRule.
This is used in the geocoding process to identify the address fields. The column names in the rule must match the ones supplied in the columns array. If the GeocodeRule is not supplied a default rule will be generated using our internal Mapsimise latitude and longitude fields.
{
"DisplayName": string,
"Columns": [
{
"FieldId": string,
"DisplayName": string,
"Type": int,
"PrimaryKey": bool
}, ...
],
"GeocodeRule": {
"AddressLine1": string,
"AddressLine2": string,
"AddressLine3": string,
"City": string,
"State": string,
"County": string,
"PostalCode": string,
"Country": string,
"DefaultCountry": string,
"Latitude": string,
"Longitude": string
}
}The update model is identical to the create model except none of the values are required.
To remove an existing column you must specify its Name:string and use the special Type "RemoveColumn". This will remove that column from the DataTable.
tableId:guid
The id of the DataTable.
DisplayName:string
Supplying this field will rename the table.
Column:array
A list of Columns to be modified.
FieldId:string
If the name does not exist in the database it will be created providing a Type:string has been supplied.
DisplayName:string
Optional name that will be displayed to end users.
Type:string
Defines the type of data to be stored in this column. If supplied for an existing column it will attempt to redefine the column to this type. This could cause data loss. See Type for a complete list of valid types.
PrimaryKey:boolean
If supplied will set the primary key for the table. If there is an existing primary key it will be removed.
A column can have all properties set in a single request. You can set the displayname, change the type and set the primary key at the same time.
Guide:dictionary
A dictionary representing the GeocodeRule.
Supplying any fields here will modify the existing rule. Setting the values to null will remove the related field from the rule.
If a null value is supplied for the Latitude and Longitude column, they will default to our internal Mapsimise Latitude and Longitude columns.
{
"DisplayName": string,
"Columns": [
{
"FieldId": string,
"DisplayName": string,
"Type": int,
"PrimaryKey": bool
}, ...
],
"GeocodeRule": {
"AddressLine1": string,
"AddressLine2": string,
"AddressLine3": string,
"City": string,
"State": string,
"County": string,
"PostalCode": string,
"Country": string,
"DefaultCountry": string,
"Latitude": string,
"Longitude": string
}
}The API allows you to create, delete, and update your records against your given DataTable. You can retrieve individual records as well as a list of records.
The API endpoint has 3 optional parameters to handle paging your data: (page, limit, and order).
tableId:guid
The id of the DataTable.
page:int
A cursor for use in pagination. When applied this will retrieve the next x records from this point. This is used alongside the Limit:int parameter in order to calculate where each page starts. The default value is 1 (first page).
limit:int
A limit on the number of records returned for each request. Limit can be between 1 and 100, and the default is 10. All other values will be ignored and reverted to this range.
order:string
The column name to order the records by. This should be kept consistent while paging your records. If not supplied the primary key field will be used. If no primary key is available, it is defaulted to our internal Mapsimise ID.
{
"Status": int,
"ResponseText": string,
"Data": [
{
"column_name": value,
"column_name": value, ...
},
{
"column_name": value,
"column_name": value, ...
}, ...
],
"MoreRecords":bool
}Retrieve a single Record from your given table. A record ID must be supplied. This can only be used if a primary key column has been specified in your DataTable.
tableId:guid
The id of the DataTable.
recordId:object
The ID of the record to retrieve. This is compared against the primary key specified on your DataTable. If no primary key has been specified this operation will fail.
The returned Data will contain a dictionary (key:value pair) of your record. The key is the name of your column.
{
"Status": int,
"ResponseText": string,
"Data": {
"column_name": value,
"column_name": value, ...
},
}Creates a record in your given DataTable.
tableId:guid
The id of the DataTable.
This is a key:value pair set. The key represents your column name.
If a primary key field has been specified, and it is not an int or GUID type, you must provide its value as part of the create.
If the primary key is specified, as an int or GUID, you can optionally specify the primary key value. If not provided the values will be populated internally with the next value in the sequence.
{
"column_name": value,
"column_name": value, ...
}Updates and existing record in your given DataTable.
tableId:guid
The id of the DataTable.
recordId:object
The ID of the record to update.
This is a dictionary (key:value pair). The key represents your column name. Only the columns that require update need be supplied. You may supply null values to clear a field. If a primary key value is present, in the list, it will be ignored.
{
"column_name": value,
"column_name": value, ...
}Deletes a record from your given DataTable.
tableId:guid
The id of the DataTable.
recordId:object
The ID of the record to delete.
{
"column_name": value,
"column_name": value, ...
}Allows for multiple record processing in a single request.
tableId:guid
The id of the DataTable.
This is a array of dictionaries (key:value pairs). The key represents your column name.
When updating an existing record, only the columns that require update need be supplied. If a primary key (ID) value has been supplied it will be used to update an existing record if available, if the record is not found the record will be treated as a new record and be inserted instead.
You may supply null values to clear the value from a field. You may supply your own primary key or allow the process to generate the key for you. (Providing the primary key is a Number or UniqueIdentifier Type. All other Type require you to supply your own ID in order to update an existing record)
[
{
"column_name": value,
"column_name": value, ...
},
{
"column_name": value,
"column_name": value, ...
}, ...
]{
"Status": 1,
"Data": {
"UpdatedRecords": "Successfully updated 4 Records",
"UpdatedRecordCount": 4,
"InsertedRecords": "No records found for update",
"InsertedRecordCount": 0
}
}The Column model is used as part of the table creation and update process.
DisplayName:string
Define a display name for your column. If this is not supplied the FieldId will be used as the display name. This can be changed at any time.
FieldId:string
This is identify of the field in the datatable. If the FieldId does not exist in the datatable it will be created providing a Type:int has also been provided.
Type:int &
Defines the type of data to be stored in this column. This is always required when creating a table.
If supplied for an existing column the system will attempt to redefine the column to this type. This could cause data loss. See Type for a complete list of valid values.
Key:boolean
If supplied this will set the primary key to this field. If there is an existing primary key it will be removed.
{
"DisplayName": string,
"FieldId": string,
"Type": int,
"PrimaryKey": bool
}A GeocodeRule contains the information for our system to geocode your data (generate a latitude and longitude).
This is achieved by matching the supplied address to known world locations.
The more detail supplied in the address the more accurate the resulting geocoding can be.
All fields are
Address*:string
The value for all fields, excluding "DefaultCountry", "Latitude" and "Logitude", must match a column, either already existing or being supplied in the column array, when creating or updating and datatable. The column must be of Type "String"
DefaultCountry:string
This is the 2 letter ISO 3166 country code. If your data is from the same country, you can set the DefaultCountry to improve geocoding.
Latitude:string & Longitude:string
The column in your datatable to store the calculated Latitude and Longitude. The column must be of Type "Decimal".
If you would prefer Mapsimise to handle this internally simply do not define them or set their value to null
To remove the association of a rule item with a column, simply provide null for its value. When updating / creating you may supply only the fields you wish you update.
{
"AddressLine1": string,
"AddressLine2": string,
"AddressLine3": string,
"City": string,
"State": string,
"County": string,
"PostalCode": string,
"Country": string,
"DefaultCountry": string,
"Latitude": string,
"Longitude": string
}Type are used to define the columns
0 - "Text" nvarchar(512) (string)
1 - "Number" int (int32)
2 - "BigNumber" bitint (int64)
3 - "Decimal" float
4 - "Guid" uniqueidentifier
8 - "YesNo" bit (boolean)
12 - "DateTime" datetime2
13 - "OptionSet" nvarchar(512) (string)
If this datatype is set, the column is treated as an option list. All unique values stored in this column will be displayed as a dropdown list to the end user. This is still a 0 -"Text" string field.
14 - "Note" nvarchar(MAX) (string)
Allow up to 2GB of text data.
{
0: "Text",
1: "Number",
2: "BigNumber",
3: "Decimal",
4: "Guid",
8: "YesNo",
12; "DateTime",
13: "OptionSet",
14: "Note"
}