MapLarge Account API Reference Version: 0.5a
Overview
The MapLarge Name-Value Pair API allows a user to remotely make changes to their account, groups, users, table resources, or permissions. All API requests are sent using GET parameters through the URL, and all responses will return a JSON formatted string, optionally wrapped in a JSONP style callback function.
Making Requests
Requests are made to a URL that is determined by the action that you are wanting to invoke.
EX: Create Table invocation: http://alphaapi.maplarge.com/Remote/CreateTable?GET-VARIABLES
Denotes required field |
Every request sent to the API is required to have three parameters for authentication purposes. There is also an optional callback parameter that will signal to the API to return in JSONP.
Required Request Parameters
mluser | string | User name to sign in with. |
mlpass -or- mltoken | string | Either the password for the mluser account or the MapLarge generated auth token for the client profile. |
callback | string | The name of the function in which to wrap the JSON return data. |
customid | string | A custom id provided by the calling script that will be returned in the response. |
Responses will be returned as a JSON formatted string, with an optional callback wrapper for JSONP requests.
Response Values
success | true/false | Whether this action was successful in its task. |
id | string | A unique 128-bit hexadecimal value that identifies this action. Length 32. |
errors | string[] | A list of any errors encountered in the execution of this action. |
timestamp | int | Integer “linux-style” timestamp. Time is in UTC. |
[extra data] | Any additional action specific values. Defined per-action below. |
Note: Any errors in one part of an API call will cause the action to fail in its entirety, and no changes will be made. |
Table Actions
CreateTable |
Request Parameters
account | string | The account code for the Account that will own this table |
tablename | string | Name to use for table, without account code prefix. Must be alpha-numeric. |
fileurl | string[] | A comma separated list of file URIs to download. |
replyto | string | If present, server will reply to this address when import completes. |
authurl | string | For use when authentication is needed before files are downloaded. |
authpostdata | string | For use when authentication is needed before files are downloaded. |
Action Specific Response Values
None initially
Action Specific Response Values using replyto
table | string | The full table name (ID) of the newly created table. |
Note: This is an asynchronous operation. When the table import has been completed a HTTP request to the address provided in the “replyto” optional parameter will be sent, if present. The API response is returned immediately, and signifies that the request has been received and is currently processing. |
CreateTableSynchronous |
Request Parameters
account | string | The account code for the Account that will own this table |
tablename | string | Name to use for table, without account code prefix. Must be alpha-numeric. |
fileurl | string[] | A comma separated list of file URIs to download. |
authurl | string | For use when authentication is needed before files are downloaded. |
authpostdata | string | For use when authentication is needed before files are downloaded. |
Action Specific Response Values
table | string | The full table name (ID) of the newly created table. |
Note: This is a synchronous operation. The request to the API will remain open while the table datafiles are downloaded and imported. This is only recommended for files of a “reasonable” size over a good connection. |
CreateTableWithFilesSynchronous |
Request Parameters
account | string | The account code for the Account that will own this table |
tablename | string | Name to use for table, without account code prefix. Must be alpha-numeric. |
Action Specific Response Values
table | string | The full table name (ID) of the newly created table. |
Note: This is a synchronous operation. The request to the API will remain open while the table datafiles are downloaded and imported. This is only recommended for files of a “reasonable” size over a good connection. Furthermore, the files themselves must be sent in the request body data via POST, and thus will require some cross domain post strategy. The API currently supports CORS. |
DeleteTable |
Request Parameters
tablename | string | Full table ID to delete in the form “account/table/version” |
Action Specific Response Values
None
DeleteAllVersions |
Request Parameters
tablename | string | Either a full table ID or active table name to delete. |
Action Specific Response Values
None
ExportTable |
Request Parameters
tablename | string | Active table name to get the full ID for. This is the active ID “account/table” |
replyto | string | URL of a page to send a reply to when the import completes. |
Note: ExportTable action is not currently supported. |
GetActiveTableID |
Request Parameters
tablename | string | Active table name to get the full ID for. This is in the form “account/table” |
Action Specific Response Values
table | string | A full table ID in the form “account/table/version” |
GetTableVersions |
Request Parameters
tablename | string | Active table name to get the full ID for. This is the active ID “account/table” |
Action Specific Response Values
versions | mixed[] | A list of table information for all versions of the given table. Contains keys id (long), acctcode (string), name (string), version (long), description (string), created (int), inram (true/false), columns (mixed[] [ id (long), type (string)]). |
GetAllTables |
Request Parameters
account | string | If present, response value will only contain tables from this account. |
verbose | true/false | Whether to use the long format OO keys for the response. Defaults to false if not present. |
Action Specific Response Values
tables | mixed[] | A list of all tables in accounts with valid permissions, and all public tables. The response can be in one of two formats: Verbose: id (string), acctcode (string), name (string), version (long), created (int), isactive (true/false), inram (true/false), columns (mixed[] [ id (long), type (string), created (long)]). Short: id (int), isactive (true/false), columns (mixed[] [ names (comma delimited string of column names), types (comma delimited string of column names)]). |
Note: The verbose list can potentially generate long wait times and a large amount of response data, depending on how many tables the user has access to. Verbose mode is not advised for time sensitive operations. |
GetActiveTables |
Request Parameters
account | string | If present, response value will only contain tables from this account. |
verbose | true/false | Whether to use the long format OO keys for the response. Defaults to false. |
Action Specific Response Values
tables | mixed[] | A list of all active tables in accounts with valid permissions, and all public tables. The response can be in one of two formats: Verbose: id (string), acctcode (string), name (string), version (long), created (int), inram (true/false), columns (mixed[] [ id (long), type (string), created (long)]). Short: id (int), columns (mixed[] [ names (comma delimited string of column names), types (comma delimited string of column names)]). |
Note: The verbose list can potentially generate long wait times and a large amount of response data, depending on how many tables the user has access to. Verbose mode is not advised for time sensitive operations. |
SetActiveTable |
Request Parameters
tablename | string | The full table ID “account/table/version” to make the active version. |
Action Specific Response Values
None
Automated Table Import Actions
CreateAutoImport |
Request Parameters
account | string | The account code for the Account that will own tables created by this import. |
importname | string | The name to assign to this automated import listing. Alpha-numeric. |
tablename | string | Table name to give to tables imported with this listing. Alpha-numeric. |
updatefrequency | int | The frequency to run auto import for this table. Value is in minutes, and must be a minimum of 5. |
remoteurl | string | A file URI to download and process. |
description | string | Text description of this automated import listing. |
versionstokeep | int | The number of previous versions of the table to keep. Defaults to keeping all. |
authurl | string | URL to send authentication requests to before downloading files from remoterurl. |
authpostdata | string | Data that will be sent with the authentication request. Data will be sent as a POST request. |
Action Specific Response Values
autoimportid | long | The ID of the newly created autoimport item. |
EditAutoImport |
Request Parameters
id | string | The ID for the autoimport to edit. |
importname | string | The name to assign to this automated import listing. Alpha-numeric. |
tablename | string | Table name to give to tables imported with this listing. Alpha-numeric. |
updatefrequency | int | The frequency to run auto import for this table. Value is in minutes, and must be a minimum of 5. |
remoteurl | string[] | A list of file URLs to download and process. |
description | string | Text description of this automated import listing. |
versionstokeep | int | The number of previous versions of the table to keep. Defaults to keeping all. |
authurl | string | URL to send authentication requests to before downloading files from remoterurl. |
authpostdata | string | Data that will be sent with the authentication request. Data will be sent as a POST request. |
Action Specific Response Values
autoimportid | long | The ID of the modified autoimport item. |
DeleteAutoImport |
Request Parameters
id | long | The ID of the auto import item to delete. This will not remove any tables created through this autoimport. |
Action Specific Response Values
autoimportid | long | The ID of the deleted autoimport item. |
ForceRunImport |
Request Parameters
id | long | The ID of the auto import item to force execution for. |
Action Specific Response Values
None
GetImportHistory |
Request Parameters
id | long | The ID of the auto import item to get a history for. |
Action Specific Response Values
history | string[] | A list of all previous import actions. |
Note: GetImportHistory action is not currently supported. |
ListAutoImports |
Request Parameters
account | string | If present, response value will only contain auto imports from this account. |
Action Specific Response Values
autoimports | mixed[] | A list of all autoimports in this account. Each autoimport item contains keys: id (long), account (string), name (string), description (string), frequency (int), remoteurl (string), authurl (string), authpostdata (string). |
User Actions
AddUserToGroups |
Request Parameters
id | long | The ID for the user to be added to list of groups. |
groups | string | A comma delimited list of group IDs to add the given user to. |
Action Specific Response Values
userid | long | The ID of the user that has been modified. |
CreateUser |
Request Parameters
username | string | User name for this user. |
password | string | Password for this user. |
string | Email address for this user. | |
tags | string | A comma delimited list of tags for this user |
groups | string | A comma delimited list of group IDs to add the given user to. |
Action Specific Response Values
userid | long | The ID of the newly created user. |
DeleteUser |
Request Parameters
id | long | The ID for the user to be deleted. |
Action Specific Response Values
userid | long | The ID of the user that has been deleted. |
EditUser |
Request Parameters
id | long | The ID for the group to be deleted. |
username | string | User name for this user. |
password | string | Password for this user. |
string | Email address for this user. | |
tags | string | A comma delimited list of tags for this user |
groups | string | A comma delimited list of group IDs to add the given user to. |
Action Specific Response Values
userid | long | The ID of the user that has been deleted. |
Note: EditUser action is not currently supported. |
ListUsers |
Request Parameters
None
Action Specific Response Values
users | mixed[] | A list of all users connected to groups in this account. Each user item contains keys: id (long), name (string), email(string), tags(string[]), groupcount(int). |
RemoveUserFromGroups |
Request Parameters
id | long | The ID for the user to be removed from list of groups. |
groups | string | A comma delimited list of group IDs to remove the given user from. |
Action Specific Response Values
userid | long | The ID of the user that has been modified. |
Group Actions
CreateGroup |
Request Parameters
account | string | The account code for the Account that will own this group. |
groupname | string | The name to use for this group. |
description | string | A description to assign to this group. |
parentgroup | long | The ID of the parent group to use for this group. If not passed, this will be a top level group. |
permissionlevel | string | The permission settings to apply to the newly created group. Must be one of the values administrator, editor, viewer. |
Action Specific Response Values
groupid | long | The ID of the newly created group. |
DeleteGroup |
Request Parameters
id | long | The ID for the group to be deleted. |
Action Specific Response Values
groupid | long | The ID of the group that has been deleted. |
EditGroup |
Request Parameters
id | long | The ID for the group to be edited. |
groupname | string | A name to assign to this group. |
description | string | A description to assign to this group. |
parentgroup | long | The ID of the parent group to use for this group. If not passed, this will be a top level group. |
permissionlevel | string | The permission settings to apply to the newly created group. Must be one of the values administrator, editor, viewer. |
Action Specific Response Values
versions | string[] | A list of table versions for “tablename” in the form “account/table/version” |
ListGroups |
Request Parameters
account | string | If present, response value will only contain groups from this account. |
Action Specific Response Values
groups | mixed[] | A list of all groups present in this account. Each group item contains the keys: id (long), account (string), name (string), description (string). |