Mapline API Documentation

Explore the possibilities.

INTRODUCTION
Welcome to the Mapline API Reference. This guide explains the Mapline application programming interface (API). It describes various API operations, related request and response structures, and error codes.
The Mapline API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf clients. JSON is returned by all API responses, including errors.
Please contact us if you are interested in learning more about Mapline’s API pricing plans and gaining access to Mapline’s API solutions.
API KEYS
In order to use the Mapline API you will need an API key associated with your account. If you own the account (Account Owner), you can manage API Keys associated with your account in the Profile Dashboard. If you are not the account owner you can use the API key generated by the Account owner for the account to authenticate yourself. Your API keys carry many privileges, so be sure to keep them secret.
ADD API KEY
Follow the below steps to add an API key to your account:
1. Click on API Keys button (Available only for Account Owners on an API accessible plan.)
2. Click On Add API Key Button.
3. Provide a description and click save to generate a new API Key.
4. A new, secret API key will be generated.
AUTHENTICATION
You will authenticate your account when using the API by including your account user email and secret API key in the request. The API is authenticated via HTTP Basic Auth. Provide your email as the basic auth username value and your API keys as the basic auth password value.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
AUTHORIZATION
The authorization to resources in the API is dependent on the role associated (Owner, Admin, User or Billing Admin) with the Mapline user email provided during authentication. For example, if you try to add a new user on the account while using the API, the request will fail if the authenticated user role is either “admin”, “user”, or “billing admin”. Only the “owner” has authorization to add a new user to the account.
USAGE LIMITS
Api usage limits are calculated on the basis of the number of operations done for each call to Mapline’s API. If the call is for retrieving or deleting an object, the number of calls deducted is always 1. However, for creating or editing an object, the number of calls also depends upon the number of subobjects being referred and the number of operations being performed.
For example, if the user wants to retrieve a map, then the number of calls deducted is 1 irrespective of how many dataset layers the map might contain or how many locations each dataset layer might contain, but if the user wants to create a new map, with a new dataset containing 5 locations, then the number of api calls counted would be 7 – 1 for creating the map, 5 for creating the dataset with 5 locations, and 1 more for adding the dataset as a layer to the newly created map.
In case the server encounters any error, only a single call will be counted. However, if the user input is erroneous, then the number of calls will depend upon the number of objects referred, as mentioned before. So, for example, if the user creates a new map with 5 existing datasets as layers, but among those 5, the user has permission over only 3, in that case too, number of calls counted will be 6 – 1 for creating a map, 3 for adding the valid datasets as layers, and 2 for the remaining 2 invalid datasets.
The API usage limits are calculated on a monthly basis. On the first day of each month, your usage count will reset to zero. Once you have reached your API usage limits, you should receive a 403 error response until the beginning of the next month.
REQUEST RATE LIMITS
API request rate limit is defined as the number of requests that can be made to Mapline’s API per second. There is a universal limit of 10 requests per second per account (note that this is not per user on an account). This limit is calculated separately from your API usage limit. Each request Mapline’s API counts towards your API rate limit. The API rate limit is recalculated each second.
For example, if you were to send 15 requests to Mapline’s API within one second, the first 10 requests would be successful and you will receive a 200 success response. The last 5 requests would receive a 403 error with the message “You have reached your limit of web api request”. You will continue to receive a 403 error message until a full second has lapsed and then your next requests would receive a success 200 response.

ERRORS

Mapline uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in 2xx range indicate success, codes in 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, you reached daily geocoding limit, etc.), and codes in the 5xx range indicates an error with Mapline’s server (these are rare).

The Error Object

Attributes

ATTRIBUTES	TYPE	REQUIRED	DESCRIPTION
`Type`	string		The type of error returned. Can be: ApiError, AuthenticationError, InvalidRequestError, UserAccessDenied, RateLimitError
`Message`	string	optional	A human-readable message providing more details about the error.
`Code`	integer	optional	Code providing additional information associated with the Error. See Error codes.

Error Types

Error	Description
`ApiError`	API Errors cover any type of problem on Mapline’s end.
`AuthenticationError`	Failure to properly authenticate yourself
`InvalidRequestError`	Invalid request error arises when your request has invalid parameters or when your request is not accepted.
`UserAccessDenied`	The user doesn’t have access to the requested resource.
`RateLimitError`	Rate Limit error arises when you have hit any of the limits associated with your account. For example, too many requests hit the API too quickly or you have reached the daily geocoding limit, etc.

Error Codes

Error Code	Description
`101`	Datasets limit reached.
`102`	Dataset records limit reached.
`103`	Daily location processing limit reached.
`106`	Maps limit reached.
`108`	Route limit reached.
`109`	Views limit reached.
`111`	Reports limit reached.
`112`	Charts limit reached.
`113`	Survey limit reached.
`114`	Collection limit reached.
`116`	Visualization limit reached.

HTTP Response Codes

HTTP Response Code	Description
`200 – OK`	Everything worked as expected.
`400 – Bad`	The request was unacceptable, often due to a missing required field.
`401 – Unauthorized`	No valid API key provided or user doesn’t have access to the resource.
`403 – Forbidden`	User doesn’t have access to lookup maps or datasets.
`404 – Not found`	The requested resource doesn’t exist.
`429 – Too many requests`	Too many requests hit the API too quickly.
`500,502,503,504`	Something went wrong on Mapline’s end.

LIST

All top-level API resources have support for bulk fetches via “list” API methods. For instance you can list maps, list datasets, and list users. These list API methods share a common structure.

The List Object

Attributes

Attribute	Type	Description
`Object`	string, value is “dataset”	–
`Data`	array	An array containing the actual response elements, paginated by any request parameters.
`HasMore`	boolean	Whether or not there are more elements available after this set. If false, this set comprises the end of the list.

DATASET

A Dataset object allows you to perform operations on datasets associated with your account. The API allows you to create and delete datasets on your account. The API allows you to retrieve individual datasets as well as a list of all your datasets.

The Dataset Object

Attributes

Attribute	Type	Description
`Id`	string	–
`Object`	string, value is “dataset”	–
`Name`	string	The name of dataset.
`Headers`	array, column object	List of all columns associated with the dataset.
`Records`	array, record object	List of all records associated with the dataset.
`RecordCount`	integer	Count of records associated with the dataset.
`Owner`	user object	Owner of the dataset
`DateCreated`	datetime	Date when dataset is first created.
`DateModified`	datetime	Date when dataset is last modified.
`CreatedBy`	string	User who created dataset
`ModifiedBy`	string	User by whom dataset is last modified

Create a Dataset

Creates a new dataset.

Arguments

Argument	Required	Description
`Name`	required	The name of the dataset.
`Headers`	required	List of column header names associated with the dataset.
`Records`	required	List of all records associated with the dataset.

Returns

Returns a dataset object if the dataset is created. Returns an error if something goes wrong.

Definition

POST https://api.mapline.com/v1/datasets

Example Request Object

{
	"Name": "My Sales",
	"Headers": [
		"NAME",
		"POSTAL CODE",
		"SALES"
	],
	"Records": [{
		"Values": [
			"Mike",
			"01005",
			"$290"
		]
	}, {
		"Values": [
			"John",
			"01010",
			"$180"
		]
	}]
}

Example Response Object

{
  "Object": "Dataset",
  "Id": "ds_351ab18c",
  "Name": "My Sales",
  "Headers": [
    {
      "Object": "Header",
      "Id": "hdr_262fa8ba",
      "Name": "NAME",
      "DateCreated": "2021-07-13T10:11:36.837",
      "Ordinal": 0,
      "CreatedBy": "Creator Name"
    },
    {
      "Object": "Header",
      "Id": "hdr_32c3eba1",
      "Name": "POSTAL CODE",
      "DateCreated": "2021-07-13T10:11:36.837",
      "AddressComponent": "PostalCode",
      "Ordinal": 1,
      "CreatedBy": "Creator Name"
    },
    {
      "Object": "Header",
      "Id": "hdr_59e62e88",
      "Name": "SALES",
      "DateCreated": "2021-07-13T10:11:36.837",
      "Ordinal": 2,
      "CreatedBy": "Creator Name"
    }
  ],
  "Records": [
    {
      "Object": "Record",
      "Id": "rec_1b2f2456",
      "DateCreated": "2021-07-13T05:11:36.867",
      "DateModified": "2021-07-13T05:11:36.867",
      "CreatedBy": "Creator Name",
      "ModifiedBy": "Modifier Name",
      "Values": [
        "Mike",
        "01005",
        "290"
      ],
      "DatasetId": "ds_351ab18c"
    },
    {
      "Object": "Record",
      "Id": "rec_27c3673d",
      "DateCreated": "2021-07-13T05:11:36.867",
      "DateModified": "2021-07-13T05:11:36.867",
      "CreatedBy": "Creator Name",
      "ModifiedBy": "Modifier Name",
      "Values": [
        "John",
        "01010",
        "180"
      ],
      "DatasetId": "ds_351ab18c"
    }
  ],
  "Owner": {
    "Email": "email@domain.com",
    "Name": "Owner Name"
  },
  "DateCreated": "2021-07-13T05:11:36.837",
  "DateModified": "2021-07-13T05:11:36.837",
  "CreatedBy": "Creator Name",
  "ModifiedBy": "Modifier Name"
  "RecordCount": 2
}

Retrieve a Dataset

Retrieves the details of an existing dataset.

Arguments

Argument	Required	Description
`Id`	required	The id of the dataset.

Returns

Returns a dataset object if a valid identifier is provided.

Definition

GET https://api.mapline.com/v1/datasets/ds_351ab18c

Example Response Object

{
  "Object": "Dataset",
  "Id": "ds_351ab18c",
  "Name": "My Sales",
  "Headers": [
    {
      "Object": "Header",
      "Id": "hdr_262fa8ba",
      "Name": "NAME",
      "DateCreated": "2021-07-13T10:11:36.837",
      "Ordinal": 0,
      "CreatedBy": "Creator Name"
    },
    {
      "Object": "Header",
      "Id": "hdr_32c3eba1",
      "Name": "POSTAL CODE",
      "DateCreated": "2021-07-13T10:11:36.837",
      "AddressComponent": "PostalCode",
      "Ordinal": 1,
      "CreatedBy": "Creator Name"
    },
    {
      "Object": "Header",
      "Id": "hdr_59e62e88",
      "Name": "SALES",
      "DateCreated": "2021-07-13T10:11:36.837",
      "Ordinal": 2,
      "CreatedBy": "Creator Name"
    }
  ],
  "Records": [
    {
      "Object": "Record",
      "Id": "rec_1b2f2456",
      "DateCreated": "2021-07-13T05:11:36.867",
      "DateModified": "2021-07-13T05:11:36.867",
      "CreatedBy": "Creator Name",
      "ModifiedBy": "Modifier Name",
      "Values": [
        "Mike",
        "01005",
        "290"
      ],
      "DatasetId": "ds_351ab18c"
    },
    {
      "Object": "Record",
      "Id": "rec_27c3673d",
      "DateCreated": "2021-07-13T05:11:36.867",
      "DateModified": "2021-07-13T05:11:36.867",
      "CreatedBy": "Creator Name",
      "ModifiedBy": "Modifier Name",
      "Values": [
        "John",
        "01010",
        "180"
      ],
      "DatasetId": "ds_351ab18c"
    }
  ],
  "Owner": {
    "Email": "email@domain.com",
    "Name": "Owner Name"
  },
  "DateCreated": "2021-07-13T05:11:36.837",
  "DateModified": "2021-07-13T05:11:36.837",
  "CreatedBy": "Creator Name",
  "ModifiedBy": "Modifier Name"
  "RecordCount": 2
}

Delete a Dataset

Permanently deletes a dataset from the account. This cannot be undone.

Arguments

Argument	Required	Description
`Id`	required	The id of the dataset.

Returns

Returns an object with a deleted parameter on success. If the dataset Id is not available, this call returns an error.

Definition

DELETE https://api.mapline.com/v1/datasets/ds_351ab18c

Example Response Object

{
	"Deleted": "true",
	"Id": "ds_351ab18c"
}

List All Datasets

Returns a list of your datasets sorted by DateModified, with the most recent modified dataset appearing first.

Returns

Returns a list object containing all your datasets.

Definition

GET https://api.mapline.com/v1/datasets

Example Response Object

{
  "Object": "List",
  "HasMore": false,
  "Limit": 10,
  "Data": [
    {
      "Object": "Dataset",
      "Id": "ds_178d50ef",
      "Name": "My Accounts",
      "Owner": {
        "Email": "owner@domain.com",
        "Name": "Owner Name"
      },
      "DateCreated": "2020-02-11T12:45:49.22",
      "DateModified": "2021-07-13T11:06:54.29",
      "CreatedBy": "Creator Name",
      "ModifiedBy": "Modifier Name",
      "RecordCount": 90
    },
    {
      "Object": "Dataset",
      "Id": "ds_43f1092",
      "Name": "Area Sales",
      "Owner": {
        "Email": "owner@domain.com",
        "Name": "Owner Name"
      },
      "DateCreated": "2021-07-13T10:53:43.033",
      "DateModified": "2021-07-13T10:53:43.37",
      "CreatedBy": "Creator Name",
      "ModifiedBy": "Modifier Name",
      "RecordCount": 2
    }
  ]
}

COLUMN

The Column object allows you to define the components of a dataset column.

Column Object

Attributes

Attribute	Type	Description
`Id`	string	–
`Object`	string, value is “Header”.	–
`Name`	string	The name of the column.
`Ordinal`	integer	Position of the column in the dataset column list.
`AddressComponent`	string	Type of address. This is available only if the column represents an address type. Allowed values are: Address, City, County, State, Country, PostalCode, Latitude, Longitude
`DateCreated`	datetime	Date when column is first created.
`DateModified`	datetime	Date when column is last modified.
`CreatedBy`	string	User who created the column.
`ModifiedBy`	string	User by whom column is last modified.

Create a Column

Creates a new column on a dataset. Currently, only static data column creation is supported.

Arguments

Argument	Required	Description
`Name`	optional	The name of the new column. If a name is not provided the new column will be created with the name “[Untitled]”.
`Ordinal`	optional	Position of the new column in the dataset column list. If a Ordinal is provided, all existing columns in the dataset with ordinal values that are equal to or greater than the ordinal of new column will shift by one.If a ordinal is not provided then the new column will be added to the end of column list.
`AddressComponent`	optional	Type of address. Provide if the new column represents an address type. If another column with the same AddressComponent type already exists on the dataset, the request will fail.

Returns

Returns a column object if the column is created. Returns an error if something goes wrong.

Definition

POST https://api.mapline.com/v1/datasets/ds_351ab18c/columns

Example Request Object

{
	"Name": "POSTAL CODE",
    "Ordinal":1,
	"AddressComponent": "PostalCode"
}

Example Response Object

{
      "Object": "Header",
      "Id": "hdr_32c3eba1",
      "Name": "POSTAL CODE",
      "DateCreated": "2021-07-13T10:11:36.837",
      "AddressComponent": "PostalCode",
      "Ordinal": 1,
      "CreatedBy": "Creator Name"
}

Retrieve a Column

Retrieves the detail of an existing column.

Arguments

Argument	Required	Description
`Id`	required	The id of the column.

Returns

Returns a column object if a valid identifier is provided.

Definition

GET https://api.mapline.com/v1/datasets/ds_351ab18c/columns/hdr_32c3eba1

Example Response Object

{
      "Object": "Header",
      "Id": "hdr_32c3eba1",
      "Name": "POSTAL CODE",
      "DateCreated": "2021-07-13T10:11:36.837",
      "AddressComponent": "PostalCode",
      "Ordinal": 2,
      "CreatedBy": "Creator Name"
}

Update a Column’s Information

Updates information about a column in a dataset.

Arguments

Argument	Required	Description
`Id`	required	ID of the column to be edited.
`Name`	optional	The updated name of the column.
`Ordinal`	optional	The updated position of the column. If an Ordinal is provided, all existing columns in the dataset with ordinal values that are equal to or greater than the ordinal of updated column will shift by one.If an Ordinal is not provided then the column position will not change.
`AddressComponent`	optional	The updated AddressComponent type. If another header with the same AddressComponent type already exists on the dataset, the request will fail.

Returns

Returns a column object if the column information is updated succesfully. Returns an error if something goes wrong.

Definition

PUT https://api.mapline.com/v1/datasets/ds_351ab18c/columns/hdr_32c3eba1

Example Request Object

{
      "Name": "SALES POSTAL CODE",
      "AddressComponent": "PostalCode",
      "Ordinal": 2
}

Example Response Object

{
      "Object": "Header",
      "Id": "ds_351ab18c",
      "Name": "SALES POSTAL CODE",
      "DateCreated": "2021-07-13T10:11:36.837",
      "AddressComponent": "PostalCode",
      "Ordinal": 2,
      "CreatedBy": "Creator Name",
      "DateModified": "2021-07-13T07:02:19.397",
      "ModifiedBy": "Modifier Name",
}

Delete a Column

Permanently deletes a column from the dataset. This cannot be undone.

Arguments

Argument	Required	Description
`Id`	required	The id of the column.

Returns

Returns an object with a deleted parameter on success. If the column ID is not available, this call returns an error.

Definition

DELETE https://api.mapline.com/v1/datasets/ds_351ab18c/columns/hdr_32c3eba1

Example Response Object

{
	"Id":"ds_351ab18c",
	"Deleted":true
}

REPROCESS A COLUMN

Initiates a dynamic data column to be queued to be processed.

Arguments

Argument	Required	Description
`Id`	required	The id of the column.

Returns

Returns a success message if the column was able to be successfully queued for processing. Returns an error message if there were any problems queuing the given header for processing.

Currently, only dynamic data columns of type Route Optimization that are set to manually reprocess are available to be reprocessed.

Definition

PUT https://api.mapline.com/v1/datasets/ds_351ab18c/columns/hdr_32c3eba2/reprocess

Example Response Object

None

RECORD

The record object provides information about a single record within a dataset associated with your account.

The Record Object

Attributes

Attribute	Type	Description
`Id`	string	–
`Object`	string, value is “Record”	–
`DatasetId`	string	The ID of the dataset the record belongs to.
`Headers`	array, Header object	Collection of headers associated with the record.
`Values`	array, string	Information for record.
`DateCreated`	datetime	Date when record is created.
`CreatedBy`	string	User who created record.
`DateModified`	datetime	Date when record was last modified.
`ModifiedBy`	string	User by whom record is last modified

Create a Record

Creates a new record in a dataset.

Arguments

Argument	Required	Description
`DatasetId`	required	Dataset to which the record will be added.
`Values`	required	Collection of values associated with the record.

Returns

Returns a record object if the record is created. Returns an error if something goes wrong.

Definition

POST https://api.mapline.com/v1/records

Example Request Object

{
	"Values": [
		"Jhon",
		"10022",
		"$100"
	],
	"DatasetId": "ds_149305c6"
}

Example Response Object

{
  "Object": "Record",
  "Id": "rec_58eb94a1",
  "DateCreated": "2021-07-13T07:02:19.397",
  "DateModified": "2021-07-13T07:02:19.397",
  "CreatedBy": "Creator Name",
  "ModifiedBy": "Modifier Name",
  "Headers": [
    {
      "Object": "Header",
      "Id": "hdr_7989b2d",
      "Name": "NAME",
      "DateCreated": "2021-06-29T10:26:58.943",
      "Ordinal": 0,
      "CreatedBy": "Creator Name"
    },
    {
      "Object": "Header",
      "Id": "hdr_12bcde14",
      "Name": "POSTAL CODE",
      "DateCreated": "2021-06-29T10:26:58.943",
      "AddressComponent": "PostalCode",
      "Ordinal": 1,
      "CreatedBy": "Creator Name"
    },
    {
      "Object": "Header",
      "Id": "hdr_3950e1fb",
      "Name": "SALES",
      "DateCreated": "2021-06-29T10:26:58.943",
      "Ordinal": 2,
      "CreatedBy": "Creator Name"
    }
  ],
  "Values": [
    "Jhon",
    "10022",
    "$100.00"
  ],
  "DatasetId": "ds_149305c6"
}

Create Multiple Records

Creates multiple new records in a dataset in a single request.

Arguments

Argument	Required	Description
`Records`	required	A list of record objects to be processed in batch.
`Headers`	required	A list of header IDs specifying record structure.
`Values`	required	A list of values corresponding to each header.

Each record must contain Headers and Values for proper processing.
Each record in the list can have different Headers for processing.
The order of Values in each record must match the order of Headers to ensure accuracy.

Returns

Returns a list of record object if the records are successfully created. Returns an error if something goes wrong.

Definition

POST https://api.mapline.com/v1/datasets/ds_149305c6/records

Example Request Object

[
    {
        "Headers": [
            {
                "Id": "hdr_51ef35a0"
            },
            {
                "Id": "hdr_7c837887"
            }
        ],
        "Values": [
            "Jhon",
            "$100"
        ]
    },
    {
        "Headers": [
            {
                "Id": "hdr_7c837887"
            },
            {
                "Id": "hdr_51ef35a2"
            }
        ],
        "Values": [
            "$150",
            "Apple"
        ]
    }
]

Example Response Object

[
    {
        "Object": "Record",
        "Id": "hdr_51ef35a0",
        "DateCreated": "2021-07-13T07:02:19.397",
        "CreatedBy": "Creator Name",
        "Headers": [
            {
                "Object": "Header",
                "Id": "hdr_51ef35a0",
                "Name": "NAME",
                "DateCreated": "2021-07-13T07:02:19.397",
                "Ordinal": 0,
                "CreatedBy": "Creator Name"
            },
            {
                "Object": "Header",
                "Id": "hdr_7c837887",
                "Name": "COST",
                "DateCreated": "2021-07-13T07:02:19.397",
                "AddressComponent": "PostalCode",
                "Ordinal": 1,
                "CreatedBy": "Creator Name"
            },
            {
                "Object": "Header",
                "Id": "hdr_51ef35a2",
                "Name": "PRODUCT",
                "DateCreated": "2021-07-13T07:02:19.397",
                "Ordinal": 2,
                "CreatedBy": "Creator Name"
            }
        ],
        "Values": [
            "Jhon",
            "$100",
            ""
        ],
        "DatasetId": "ds_149305c6"
    },
    {
        "Object": "Record",
        "Id": "rec_58eb94b1",
        "DateCreated": "2021-07-13T07:02:19.397",
        "CreatedBy": "Creator Name",
        "Headers": [
            {
                "Object": "Header",
                "Id": "hdr_51ef35a0",
                "Name": "NAME",
                "DateCreated": "2021-07-13T07:02:19.397",
                "Ordinal": 0,
                "CreatedBy": "Creator Name"
            },
            {
                "Object": "Header",
                "Id": "hdr_7c837887",
                "Name": "PRODUCT",
                "DateCreated": "2021-07-13T07:02:19.397",
                "AddressComponent": "PostalCode",
                "Ordinal": 1,
                "CreatedBy": "Creator Name"
            },
            {
                "Object": "Header",
                "Id": "hdr_51ef35a2",
                "Name": "COST",
                "DateCreated": "2021-07-13T07:02:19.397",
                "Ordinal": 2,
                "CreatedBy": "Creator Name"
            }
        ],
        "Values": [
            "",
            "$150",
            "Apple"
        ],
        "DatasetId": "ds_149305c6"
    }
]

Retrieve a Record

Retrieves the details of an existing record.

Arguments

Argument	Required	Description
`Id`	required	The id of the record.

Returns

Returns a record object if a valid identifier is provided.

Definition

GET https://api.mapline.com/v1/records/rec_58eb94a1

Example Response Object

{
  "Object": "Record",
  "Id": "rec_58eb94a1",
  "DateCreated": "2021-07-13T07:02:19.397",
  "DateModified": "2021-07-13T07:02:19.397",
  "CreatedBy": "Creator Name",
  "ModifiedBy": "Modifier Name",
  "Headers": [
    {
      "Object": "Header",
      "Id": "hdr_7989b2d",
      "Name": "NAME",
      "DateCreated": "2021-06-29T10:26:58.943",
      "Ordinal": 0,
      "CreatedBy": "Creator Name"
    },
    {
      "Object": "Header",
      "Id": "hdr_12bcde14",
      "Name": "POSTAL CODE",
      "DateCreated": "2021-06-29T10:26:58.943",
      "AddressComponent": "PostalCode",
      "Ordinal": 1,
      "CreatedBy": "Creator Name"
    },
    {
      "Object": "Header",
      "Id": "hdr_3950e1fb",
      "Name": "SALES",
      "DateCreated": "2021-06-29T10:26:58.943",
      "Ordinal": 2,
      "CreatedBy": "Creator Name"
    }
  ],
  "Values": [
    "Jhon",
    "10022",
    "$100.00"
  ],
  "DatasetId": "ds_149305c6"
}

Update a Record’s Information

Updates information about a record within a dataset.

Arguments

Argument	Required	Description
`Id`	required	ID of the record to be edited.
`Values`	required	Collection of values associated with the record.

Returns

Returns a record object if the record is created. Returns an error if something goes wrong.

Definition

PUT https://api.mapline.com/v1/records/rec_58eb94a1

Example Request Object

{
	"Values":[
		"Sally",
		"60563",
		"$500"
	]
}

Example Response Object

{
  "Object": "Record",
  "Id": "rec_58eb94a1",
  "DateCreated": "2021-07-13T07:02:19.397",
  "DateModified": "2021-07-13T07:02:19.397",
  "CreatedBy": "Creator Name",
  "ModifiedBy": "Modifier Name",
  "Headers": [
    {
      "Object": "Header",
      "Id": "hdr_7989b2d",
      "Name": "NAME",
      "DateCreated": "2021-06-29T10:26:58.943",
      "Ordinal": 0,
      "CreatedBy": "Creator Name"
    },
    {
      "Object": "Header",
      "Id": "hdr_12bcde14",
      "Name": "POSTAL CODE",
      "DateCreated": "2021-06-29T10:26:58.943",
      "AddressComponent": "PostalCode",
      "Ordinal": 1,
      "CreatedBy": "Creator Name"
    },
    {
      "Object": "Header",
      "Id": "hdr_3950e1fb",
      "Name": "SALES",
      "DateCreated": "2021-06-29T10:26:58.943",
      "Ordinal": 2,
      "CreatedBy": "Creator Name"
    }
  ],
  "Values": [
    "Sally",
    "60563",
    "$500"
  ],
  "DatasetId": "ds_149305c6"
}

Update multiple Record’s Information

Updates information for multiple records within a dataset.

Arguments

Argument	Required	Description
`Id`	required	ID of the record to be modified.
`Headers`	required	A list of header IDs specifying record structure.
`Values`	required	A list of values corresponding to each header.

Each record must contain Id, Headers and Values for proper processing.
Each record in the list can have different Headers based on its structure.
The order of Values in each record must match the order of Headers to ensure accuracy.

Returns

Returns a list of record objects containing updated information if successful. Returns an error if something goes wrong.

Definition

PUT https://api.mapline.com/v1/datasets/ds_37368079/records

Example Request Object

[
    {
        "Id": "rec_2167fc25561400",
        "Headers": [
            {
                "Id": "hdr_51ef35a0"
            },
            {
                "Id": "hdr_7c837887"
            },
            {
                "Id": "hdr_ba7bc6e"
            }
        ],
        "Values": [
            "01010",
            "180.00",
            "John"
        ]
    },
    {
        "Id": "rec_2167fc255c1400",
        "Headers": [
            {
                "Id": "hdr_51ef35a0"
            },
            {
                "Id": "hdr_7c837887"
            },
            {
                "Id": "hdr_ba7bc6e"
            }
        ],
        "Values": [
            "01005",
            "290.00",
            "Mike"
        ]
    }
]

Example Response Object

[
    {
        "Object": "Record",
        "Id": "rec_2167fc25561400",
        "DateModified": "2025-04-10T09:34:50.809",
        "ModifiedBy": "Modifier Name",
        "Headers": [
            {
                "Object": "Header",
                "Id": "hdr_51ef35a0",
                "Name": "POSTAL CODE",
                "Type": "UserData",
                "Ordinal": 0
            },
            {
                "Object": "Header",
                "Id": "hdr_7c837887",
                "Name": "SALES",
                "Type": "UserData",
                "Ordinal": 1
            },
            {
                "Object": "Header",
                "Id": "hdr_ba7bc6e",
                "Name": "NAME",
                "Type": "UserData",
                "Ordinal": 2
            }
        ],
        "Values": [
            "01010",
            "180.00",
            "John"
        ],
        "DatasetId": "ds_37368079"
    },
    {
        "Object": "Record",
        "Id": "rec_2167fc255c1400",
        "DateModified": "2025-04-10T09:34:50.809",
        "ModifiedBy": "Modifier Name",
        "Headers": [
            {
                "Object": "Header",
                "Id": "hdr_51ef35a0",
                "Name": "POSTAL CODE",
                "Type": "UserData",
                "Ordinal": 0
            },
            {
                "Object": "Header",
                "Id": "hdr_7c837887",
                "Name": "SALES",
                "Type": "UserData",
                "Ordinal": 1
            },
            {
                "Object": "Header",
                "Id": "hdr_ba7bc6e",
                "Name": "NAME",
                "Type": "UserData",
                "Ordinal": 2
            }
        ],
        "Values": [
            "01005",
            "290.00",
            "Mike"
        ],
        "DatasetId": "ds_37368079"
    }
]

Delete a Record

Permanently deletes a record from the account. This cannot be undone.

Arguments

Argument	Required	Description
`dataset_Id`	required	The id of the record.

Returns

Returns an object with a deleted parameter on success. If the record ID is not available, this call returns an error.

Definition

DELETE https://api.mapline.com/v1/records/rec_4505e7bd

Example Response Object

{
	"Id":"rec_4505e7bd",
	"Deleted":true
}

Delete multiple Records

Permanently deletes multiple records from the dataset. This cannot be undone.

Arguments

Argument	Required	Description
`RecordIds`	required	A list of record Ids to be deleted in batch.

Returns

Returns an list of objects, each containing a Deleted parameter indicating success.

Definition

DELETE https://api.mapline.com/v1/datasets/ds_37368079/records

Example Request Object

[
    "rec_2167fc25561400",
    "rec_2167fc255c1400"
]

Example Response Object

[
    {
        "Id": "rec_2167fc25561400",
        "deleted": true
    },
    {
        "Id": "rec_2167fc255c1400",
        "deleted": true
    }
]

MAP

Map object allows you to perform operations on maps associated with your account. The API allows you to create, delete, and update maps on your account. The API allows you to retrieve individual maps as well as a list of all your maps.

The Map Object

Attributes

Attribute	Type	Description
`Id`	string	–
`Object`	string, value is “map”	–
`Name`	string	The name of the map.
`Layers`	array, Layer object	List of all layers associated with the map.
`MapUrl`	string	Url to access map.
`Owner`	user object	Owner of the map
`DateCreated`	datetime	Date when map is first created.
`DateModified`	datetime	Date when map is last modified.
`CreatedBy`	string	User who created map
`ModifiedBy`	string	User by whom map is last modified

Create a Map

Creates a new map.

Arguments

Argument	Required	Description
`Name`	optional	The name of the map. If a name is not provided the new map will be created with the name “Untitled map”.

Returns

Returns a map object if the map is created. Returns an error if something goes wrong.

Definition

POST https://api.mapline.com/v1/maps

Example Request Object

{
  "Name": "Area Sales Map" 
}

Example Response Object

{
  "Object": "Map",
  "Id": "map_40a57051",
  "Name": "Area Sales Map",
  "MapUrl": "https://app.mapline.com/map/map_40a57051",
  "DateCreated": "2021-07-13T22:22:04.07",
  "Owner": {
    "Email": "email@domain.com",
    "Name": "Owner Name"
  }
}

Retrieve a Map

Retrieves the details of an existing map.

Arguments

Argument	Required	Description
`id`	required	The id of the map.

Returns

Returns a map object if a valid identifier is provided.

Definition

GET https://api.mapline.com/v1/maps/map_40a57051

Example Response Object

{
  "Object": "Map",
  "Id": "map_40a57051",
  "Name": "Area Sales Map",
  "MapUrl": "https://app.mapline.com/map/map_40a57051",
  "DateCreated": "2021-07-13T22:22:04.07",
  "Owner": {
    "Email": "email@domain.com",
    "Name": "Owner Name"
  }
}

Delete a Map

Permanently deletes a map from the account. This cannot be undone.

Arguments

Argument	Required	Description
`id`	required	The id of the map.

Returns

Returns an object with a deleted parameter on success. If the map id is not available, this call returns an error.

Definition

DELETE https://api.mapline.com/v1/maps/map_64fedf4f

Example Response Object

{
	"Deleted": "true",
	"Id": "map_64fedf4"
}

List All Maps

Returns a list of your maps sorted by DateCreated, with the most recent maps appearing first.

Returns

Returns a list object containing all your maps.

Definition

GET https://api.mapline.com/v1/maps

Example Response Object

{
  "Object": "List",
  "HasMore": false,
  "Data": [
    {
      "Object": "Map",
      "Id": "map_525699dd",
      "Name": "My Area Sales",
      "MapUrl": "https://app.mapline.com/map/map_525699dd",
      "Owner": {
        "Email": "email@domain.com",
        "Name": "Owner Email"
      },
      "DateCreated": "2021-07-08T02:40:26.08",
      "DateModified": "2021-07-09T02:43:37.043",
      "CreatedBy": "Owner Name",
      "ModifiedBy": "Modifier Name"
    },
    {
      "Object": "Map",
      "Id": "map_660be3ad",
      "Name": "World Countries",
      "MapUrl": "https://app.mapline.com/map/map_660be3ad",
      "Owner": {
        "Email": "email@damin.com",
        "Name": "Owner Name"
      },
      "DateCreated": "2021-06-04T04:12:43.207",
      "DateModified": "2021-06-11T14:12:23.467",
      "CreatedBy": "Owner Name",
      "ModifiedBy": "Modifier Name"
    }
  ]
}

LAYER

The Layer object represents a group of pins, line, route or territories on a map.

Layer Object

Attributes

Attribute	Type	Description
`Id`	string	–
`Object`	string	The type of layer returned. Can be PinGroup, Territory, Route, LineGroup, Segment, Folder.
`Name`	string	The name of layer.
`Style`	LayerStyle object	The style of the layer.
`Children`	array, Layer	List of all children layer associated with this layer.
`DataSource`	Dataset object, optional	Dataset associated with the layer.
`Filter`	filter object	Filter settings applied on the layer.
`IsVisible`	boolean	true if the layer is visible on map otherwise, false.
`IsCollapsed`	boolean	true if the layer children are collapsed on the map sidebar otherwise, false

CHILDREN

The Children object represents a pin, route stop point, or shape (line, circle, or territory) on a map.

Children Object

Attributes

Attribute	Type	Description
`Id`	string	–
`Object`	string	The type of children returned. Can be Pin, StopPoint, Shape
`Name`	string	The name of children.
`Style`	LayerStyle object, optional	The style associated with the children layer.
`IsVisible`	boolean, optional	true if the layer is visible on map otherwise, false, not available with StopPoint.

PUBLISHED MAP

You can publish a map for public viewing using a published object.

Publish Settings Object

The Publish Settings object allows the user to configure different settings when the map is made public and is viewed via the PublishedUrl property.

Attributes

Attribute	Type	Description
`IsPublished`	boolean	true if the map is published, otherwise, false.
`PublishedUrl`	string	The url to access the published map. This is a read only property and cannot be altered.
`ShowSidebar`	boolean	This setting determines whether the sidebar will be shown or not when the map is viewed via the PublicUrl. Default is false.
`SearchPosition`	string	This setting determines the position of the search box. Can be sidebar map
`LockPosition`	boolean	true if the map pan and zoom is disabled, otherwise, false.

Get the Publish Settings of a Map

Get a list of settings which would apply when the map is made public and is viewed via the PublicUrl.

Arguments

Argument	Required	Description
`Id`	required	The id of the map.

Returns

Returns an object containing all publish settings for the map referenced by the id argument.

Definition

`GET https://api.mapline.com/maps/map_64fedf4/publish-settings`

Example Response Object

{  
   "ShowSidebar":false,
}

Change the Publish Settings of a Map

Changes the Public Settings of a map.

Arguments

Argument	Required	Description
`Id`	required	The id of the map.
`ShowSidebar`	required	This flag determines whether the sidebar would be visible or not when the map is viewed via the PublicUrl property.

Returns

Returns an object containing all publish settings for the map referenced by the id argument.

Definition

`PUT https://api.mapline.com/maps/map_64fedf4/publish-settings`

Example Request Object

{  
   "ShowSidebar":true,
}

Example Response Object

{  
   "ShowSidebar":true,
}

USERS

Users object provides information about the account users.

The User Object

Attributes

Attribute	Type	Description
`Email`	string	Email of the user
`Object`	string, value is “user”	–
`Role`	string	Role of the user(Owner, Admin, Creator, Collaborator or Billing Admin)
`CanAccessFinance`	boolean	If true, the user has access to invoices.
`PreferredDistanceUnit`	string	User preferred distance unit (Miles, Kilometers, Yards, or Meters). Default is “Miles”.
`DateCreated`	timestamp	Date when the user was created.
`DateModified`	timestamp	Date when user was last modified.

Create a User

Creates a new user.

Arguments

Argument	Required	Description
`Email`	required	The email of the user.
`Name`	required	Name of the user.
`Role`	required	Role of the user.
`CanAccessFinance`	optional	If true, the user has access to invoices.
`PreferredDistanceUnit`	optional	User preferred distance unit (Miles, Kilometers, Yards, or Meters).

Returns

Returns a user object if the user is created. Returns an error if something goes wrong.

Definition

POST https://api.mapline.com/v1/users

Example Request Object

{
	"Email": "useremail@domain.com",
	"Name": "User Name",
	"Role": "Owner"
}

Example Response Object

{
	"Object": "user",
	"Email": "useremail@domain.com",
	"Name": "User Name",
	"Role": "Owner",
	"CanAccessFinance": true,
	"PreferredDistanceUnit": "Miles",
	"DateCreated": "2016-06-04T13:08:36.54",
	"DateModified": "2016-07-01T19:38:13.047"
}

Retrieve a User

Retrieves the details of an existing user. Only the owner can retrieve details of all other account users.

Arguments

Argument	Required	Description
`Email`	required	The email of the user.

Returns

Returns a user object if a valid email is provided.

Definition

GET https://api.mapline.com/v1/users/useremail@domain.com/

Example Response Object

{
	"Object": "user",
	"Email": "useremail@domain.com",
	"Name": "User Name",
	"Role": "Owner",
	"CanAccessFinance": true,
	"PreferredDistanceUnit": "Miles",
	"DateCreated": "2016-06-04T13:08:36.54",
	"DateModified": "2016-07-01T19:38:13.047"
}

Delete a User

Permanently deletes a user from the account. This cannot be undone.

Arguments

Argument	Required	Description
`Email`	required	The email of the user.

Returns

Returns an object with deleted parameter on success. If the email id is not available, this call returns an error.

Definition

DELETE https://api.mapline.com/v1/users/useremail@domain.com/

Example Response Object

{
	"Deleted": "true",
	"Id": "useremail@domain.com"
}

List All Users

Returns a list of all users on your account. This feature is only accessible to Account Owner.

Returns

Returns a list object containing all your users.

Definition

GET https://api.mapline.com/v1/users

Example Response Object

{
	"Object": "list",
	"HasMore": false,
	"Data": [{
		"Object": "user",
		"Email": "user1email@domain.com",
		"Name": "User1 Name",
		"Role": "Owner",
		"CanAccessFinance": true,
		"PreferredDistanceUnit": "Meters",
		"DateCreated": "2015-06-04T13:08:36.54",
		"DateModified": "2015-07-01T19:38:13.047"
	}, {
		"Object": "user",
		"Email": "user2email@domain.com",
		"Name": "User2 Email",
		"Role": "Administrator",
		"CanAccessFinance": false,
		"PreferredDistanceUnit": "Meters",
		"DateCreated": "2016-01-13T13:44:52.697",
		"DateModified": "2016-01-20T11:26:04.307"
	}]
}

Give us a call. We'd love to talk!

+1 800.969.1454

Give us a call. We'd love to talk!

+1.888.670.3795

Experience the power

Experience the power

Experience the power

Experience the power

Mapline API Documentation

INTRODUCTION

API KEYS

ADD API KEY

AUTHENTICATION

AUTHORIZATION

USAGE LIMITS

REQUEST RATE LIMITS

ERRORS

The Error Object

Attributes

Error Types

Error Codes

HTTP Response Codes

LIST

The List Object

Attributes

DATASET

The Dataset Object

Attributes

Create a Dataset

Arguments

Returns

Definition

Example Request Object

Example Response Object

Retrieve a Dataset

Arguments

Returns

Definition

Example Response Object

Delete a Dataset

Arguments

Returns

Definition

Example Response Object

List All Datasets

Returns

Definition

Example Response Object

COLUMN

Column Object

Attributes

Create a Column

Arguments

Returns

Definition

Example Request Object

Example Response Object

Retrieve a Column

Arguments

Returns

Definition

Example Response Object

Update a Column’s Information

Arguments

Returns

Definition

Example Request Object

Example Response Object

Delete a Column

Arguments

Returns

Definition

Example Response Object

REPROCESS A COLUMN

Arguments

Returns

Definition

Example Response Object

RECORD

The Record Object