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 current version of the Mapline API is 2016-06-27.
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 is 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 API key generated by 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 and 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 “owner” has authorization to add a new user to account.

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

Attribute	Required	Description
`Type`		The type of error returned. Can be: ApiError, AuthenticationError, InvalidRequestError, UserAccessDenied, RateLimitError
`Message`	optional	A human-readable message providing more details about the error.
`Param`	optional	The parameter the error relates to if the error is parameter-specific.

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.

Errors

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 requested resource.
`RateLimitError`	Rate Limit error arises when you have hit any of the limits associated with your account. For example, too many request hit the API too quickly or you have reached the daily geocoding limit, etc.

USAGE LIMITS
Api calls are calculated on the basis of the number of operations done. 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.

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.

OWNER
Owner object provides information about the owner of the requested resource. For example, the owner object is added when you request a map to provide information on who is the owner of requested map.
The Owner Object
Attributes
Attribute Type Description
Name string The name of the owner.
Email string The email of the owner.
PERMISSION
PERMISSION object provides enumeration value about the permission you have on the requested resource.
The Permission Object
Attributes
Attribute Type Description
Name string The enumeration value. The possible values are: None Read Write Full

Attribute	Type	Description
`Name`	string	The name of the owner.
`Email`	string	The email of the owner.

Attribute	Type	Description
`Name`	string	The enumeration value. The possible values are: None Read Write Full

DATASET

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 list of all your datasets.

The Dataset Object

Attritubes

Attribute	Type	Description
`Id`	string	–
`Object`	string, value is “dataset”	–
`Name`	string	The name of dataset.
`Headers`	list, header object	List of all column headers associated with the dataset.
`Records`	list, record object	List of all records associated with the dataset.
`RecordCount`	integer	Count of records associated with the dataset.
`Maps`	list, map object	List of all maps where this dataset is added as a layer.
`MapCount`	integer	Count of maps containing this dataset.
`Owner`	hash, owner object	Owner of the dataset
`Processing`	boolean	If true, dataset is still processing (geocoding) its records.
`ProcessedRecordCount`	integer	If processing is true, it will return the number of records already processed (geocoded).
`DateCreated`	timestamp	Date when dataset is first created.
`DateModified`	timestamp	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`	list, 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": "Test Dataset",
	"Headers": [
		"NAME",
		"POSTAL CODE",
		"SALES"
	],
	"Records": [{
		"Values": [
			"Mike",
			"01005",
			"$290"
		]
	}, {
		"Values": [
			"John",
			"01010",
			"$180"
		]
	}]
}

Example Response Object

{
	"Object": "dataset",
	"Id": "ds_249740e8",
	"Name": "Test Dataset",
	"Headers": [{
		"Object":"Header",
        "Id":"hdr_54dfe621",
        "Name":"NAME",
        "IsTitle":true,
        "Type":0,
        "Ordinal":0
	},{
        "Object":"Header",
        "Id":"hdr_63f22908",
        "Name":"POSTAL CODE",
        "AddressComponent":"PostalCode"
        "Type":1,
        "Ordinal":1
    },{
        "Object":"Header",
        "Id":"hdr_e966cef",
        "Name":"SALES",
        "Type":1,
        "Ordinal":2
    }],
	"Records": [{
		"Id": "rec_31cdaa92",
		"Values": [
			"Mike",
			"01005",
			"$290"
		],
		"Error": false,
		"DateCreated": "2015-06-24T00:00:00",
		"DateModified": "2015-06-24T00:00:00",
        "CreatedBy": "Creator name",
        "ModifiedBy": "Modifier name"
	}, {
		"Id": "rec_5ce1ee7d",
		"Values": [
			"John",
			"01010",
			"$180"
		],
		"Error": false,
		"DateCreated": "2015-06-24T00:00:00",
		"DateModified": "2015-06-24T00:00:00",
        "CreatedBy": "Creator name",
        "ModifiedBy": "Modifier name"
	}],
	"Owner": {
		"Name": "Owner Name",
		"Email": "owneremail@domain.com"
	},
	"RecordCount": 2,
	"MapCount": 0,
	"Processing": false,
	"ProcessedRecordCount": 0,
	"DateCreated": "2015-06-24T00:00:00",
	"DateModified": "2015-06-24T00:00:00",
    "CreatedBy": "Creator name",
    "ModifiedBy": "Modifier name"
}

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_249740e8

Example Response Object

{
	"Object": "dataset",
	"Id": "ds_249740e8",
	"Name": "Test Dataset",
	"Headers": [{
		"Object":"Header",
        "Id":"hdr_54dfe621",
        "Name":"NAME",
        "IsTitle":true,
        "Type":0,
        "Ordinal":0
	},{
        "Object":"Header",
        "Id":"hdr_63f22908",
        "Name":"POSTAL CODE",
        "AddressComponent":"PostalCode"
        "Type":1,
        "Ordinal":1
    },{
        "Object":"Header",
        "Id":"hdr_e966cef",
        "Name":"SALES",
        "Type":1,
        "Ordinal":2
    }],
	"Records": [{
		"Id": "rec_31cdaa92",
		"Values": [
			"Mike",
			"01005",
			"$290"
		],
		"Error": false,
		"DateCreated": "2015-06-24T00:00:00",
		"DateModified": "0001-01-01T00:00:00",
        "CreatedBy": "Creator name",
        "ModifiedBy": "Modifier name"
	}, {
		"Id": "rec_5ce1ee7d",
		"Values": [
			"John",
			"01010",
			"$180"
		],
		"Error": false,
		"DateCreated": "2015-06-24T00:00:00",
		"DateModified": "0001-01-01T00:00:00",
        "CreatedBy": "Creator name",
        "ModifiedBy": "Modifier name"
	}],
	"Owner": {
		"Name": "Owner Name",
		"Email": "owneremail@domain.com"
	},
	"RecordCount": 2,
	"MapCount": 0,
	"Processing": false,
	"ProcessedRecordCount": 0,
	"DateCreated": "2015-06-24T00:00:00",
	"DateModified": "2015-06-24T00:00:00",
    "CreatedBy": "Creator name",
    "ModifiedBy": "Modifier name"
}

Replace a Dataset

Deletes an existing dataset and replaces it with a new version.

Arguments

Argument	Required	Description
`Id`	required	The id of the dataset.
`Headers`	required	Headers for the dataset fields.
`Values`	required	Collection of values associated with the record.

Returns

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

Definition

PUT https://api.mapline.com/v1/datasets/ds_12499c73

Example Request Object

{
	"Headers": [
		"NAME",
		"POSTAL CODE",
		"SALES"
	],
	"Records": [{
		"Values": [
			"Mike",
			"01005",
			"$290"]
		},{
		"Values": [
			"Jim",
			"01106",
			"$452"],
		}
}

Example Response Object

{
	"Object":"dataset",
	"Id":"ds_12499c73",
	"Name":"Test Dataset",
	"Headers": [{
		"Object":"Header",
        "Id":"hdr_54dfe621",
        "Name":"NAME",
        "IsTitle":true,
        "Type":0,
        "Ordinal":0
	},{
        "Object":"Header",
        "Id":"hdr_63f22908",
        "Name":"POSTAL CODE",
        "AddressComponent":"PostalCode"
        "Type":1,
        "Ordinal":1
    },{
        "Object":"Header",
        "Id":"hdr_e966cef",
        "Name":"SALES",
        "Type":1,
        "Ordinal":2
    }],
	"Owner":{"Name":"Owner Name","Email":"owner.email@domain.com"},
	"Permission":"Full",
	"Type":0,
	"RecordCount":2,
	"MapCount":0,
	"Processing":false,
	"ProcessedRecordCount":0,
	"DateCreated":"2016-12-21T14:12:11.247",
	"DateModified":"2016-12-21T14:16:42.05",
    "CreatedBy": "Creator name",
    "ModifiedBy": "Modifier name"
}

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 deleted parameter on success. If the dataset Id is not available, this calls returns an error.

Definition

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

Example Response Object

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

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,
	"Data": [{
		"Object": "dataset",
		"Id": "ds_249740ea",
		"Name": "Dataset Name",
		"Owner": {
			"Name": "Owner Name",
			"Email": "owner.email@domain.com"
		},
		"RecordCount": 248,
		"MapCount": 0,
		"Processing": false,
		"ProcessedRecordCount": 0,
		"DateCreated": "2015-06-24T00:00:00",
		"DateModified": "2015-06-24T00:00:00",
        "CreatedBy": "Creator name",
        "ModifiedBy": "Modifier name"
	}, {
		"Object": "dataset",
		"Id": "ds_33ab83d1",
		"Name": "Dataset 2 Name",
		"Owner": {
			"Name": "Owner Name",
			"Email": "owner.email@domain.com"
		},
		"RecordCount": 523,
		"MapCount": 0,
		"Processing": false,
		"ProcessedRecordCount": 0,
		"DateCreated": "2015-06-24T00:00:00",
		"DateModified": "2015-06-24T00:00:00",
        "CreatedBy": "Creator name",
        "ModifiedBy": "Modifier name"
	}]
}

HEADERS

The Header object allows you to define the components of a header

Header Object

Attritubes

Attribute	Type	Description
`Id`	string	–
`Object`	string, value is “Header”.	–
`Name`	string	The name of header.
`IsTitle`	boolean	If this is true, then it is the name of the Record.
`Type`	integer	Data type of the header. We currently allow two values: 0 – for string type 1 – for integer type
`Ordinal`	integer	Position of the header in the dataset.
`AddressComponent`	Enumeration	Type of address. This is available only if the header represents an address type. Allowed values are: Address, City, County, State, Country, PostalCode, Latitude, Longitude

RECORD

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

The Record Object

Attritubes

Attribute	Type	Description
`Id`	string	–
`Object`	string, value is “record”	–
`DatasetId`	string	The ID of the dataset the record belongs to.
`Headers`	list of headers object (Header object: Name, Ordinal, Type)	Collection of headers associated with the record.
`DateModified`	timestamp	Date when record was last modified.
`Values`	array of string	Information for record.
`DateCreated`	timestamp	Date when record is created.
`CreatedBy`	string	User who created record.
`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": [
		"10022",
		"10022",
		"United States",
		"21502.86"
	],
	"DatasetId": "ds_45032917"
}

Example Response Object

{
	"DatasetId": "ds_249740e8",
	"DateModified": "2015-06-24T00:00:00",
    "DateCreated": "2015-06-24T00:00:00",
    "CreatedBy": "Creator name",
    "ModifiedBy": "Modifier name",
	"Error": false,
	"Headers": [
		"NAME",
		"POSTAL CODE",
		"SALES"
	],
	"Values": [
		"Mike",
		"01005",
		"$290"
	]
}

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_4162298c

Example Response Object

{
	"Id":"rec_4162298c",
	"Headers":[{
		"Name":"Name",
		"Type":0,
		"Ordinal":0
		},{
		"Name":"Address",
		"Type":0,
		"Ordinal":1
		},{
		"Name":"City",
		"Type":0,
		"Ordinal":2
		},{
		"Name":"State",
		"Type":0,
		"Ordinal":3
		},{
		"Name":"Zip",
		"Type":1,
		"Ordinal":4
		},{
		"Name":"Segment",
		"Type":0,
		"Ordinal":5
		},{
		"Name":"Sales",
		"Type":0,
		"Ordinal":6
	}],
	"Values":[
		"IN-N-OUT Burger - Avondale",
		"1525 Dysart Road",
		"Avondale",
		"AZ",
		"85323",
		"Passive",
		"High"
	],
	"Error":false,
	"DateModified":"2016-12-20T09:15:09.913",
    "DateCreated": "2016-12-20T09:15:09.913",
    "CreatedBy": "Creator name",
    "ModifiedBy": "Modifier name",
	"DatasetId":"ds_4a66053d"
}

Update a Record’s Information

Updates information about a record in 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_48ab7a27

Example Request Object

{
	"Id":"rec_48ab7a27",
	"Values":[
		"IN-N-OUT Burger - Avondale",
		"1525 Dysart Road",
		"Avondale",
		"AZ",
		"85323",
		"Passive",
		"High"
	]
}

Example Response Object

{
	"Id":"rec_48ab7a27",
	"Headers":[{
		"Name":"Name",
		"Type":0,
		"Ordinal":0
		},{
		"Name":"Address",
		"Type":0,
		"Ordinal":1
		},{
		"Name":"City",
		"Type":0,
		"Ordinal":2
		},{
		"Name":"State",
		"Type":0,
		"Ordinal":3
		},{
		"Name":"Zip",
		"Type":1,
		"Ordinal":4
		},{
		"Name":"Segment",
		"Type":0,
		"Ordinal":5
		},{
		"Name":"Sales",
		"Type":0,
		"Ordinal":6
	}],
	"Values":[
		"IN-N-OUT Burger - Avondale",
		"1525 Dysart Road",
		"Avondale",
		"AZ",
		"85323",
		"Passive",
		"High"
	],
	"Error":true,
	"DateModified":"2016-12-21T13:44:04.697",
    "DateCreated": "2016-12-20T09:15:09.913",
    "CreatedBy": "Creator name",
    "ModifiedBy": "Modifier name",
	"DatasetId":"ds_4a66053d"
}

Delete a Record

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

Arguments

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

Returns

Returns an object with 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,
	"Message":null
}

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 list of all your maps.

The Map Object

Attributes

Attribute	Type	Description
`Id`	string	–
`Object`	string, value is “map”	–
`Name`	string	The name of map.
`Datasets`	list, dataset object	List of all user datasets associated with the map.
`DatasetCount`	integer	Count of user datasets associated with the map.
`IsPublic`	boolean	If true, the map can be accessible using PublicUrl.
`MapUrl`	string	Url to access map.
`PublicUrl`	string	URL access to the map as public read only. Available only when IsPublic is set to true.
`Permission`	enumeration, permission object	Permission you have as a user on the map.
`Type`	enumeration, ownership object	The ownership type of map.
`Owner`	hash, owner object	Owner of the map.
`DateCreated`	timestamp(CST)	Date when dataset is first created.
`DateModified`	timestamp(CST)	Date when dataset is last modified.

Create a Map

Creates a new map. You can also provide a list of datasets (existing and new) along with a map that need to be added to a map after it was created.

Arguments

Argument	Required	Description
`Name`	optional	The name of the dataset. If a name is not provided the new map will be created with the name “Untitled map”.
`Datasets`	optional	List of datasets that need to be added to map. The list can contain existing datasets or new datasets. For existing datasets, just provide the id of the dataset. For new datasets, see CREATE A DATASET section for required and optional field.
`IsPublic`	optional	If true, the map will be accessible publicly using PublicUrl. Default is false.

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": "New Map Name",
	"IsPublic": "true",
	"Datasets": [{
		"Id": "ds_4650feca"
	}, {
		"Name": "new dataset",
		"Records": [{
			"Values": [
				"record 1 Name",
				"record 1 Address",
				"record 1 Sales Data"
			]
		}, {
			"Values": [
				"record 2 Name",
				"record 2 Address",
				"record 2 Sales Data"
			]
		}],
		"Headers": [
			"Name",
			"ADDRESS",
			"SALES DATA"
		]
	}]
}

Example Response Object

{
	"Object": "map",
	"Id": "map_64fedf4f",
	"Name": "territory test",
	"IsPublic": "true",
	"MapUrl": "https://app.mapline.com/maps/123456",
	"PublicUrl": "https://app.mapline.com/maps/123456/asdwse2ismasmdssadskd/true",
	"DatasetCount": 2,
	"Datasets": [{
		"Object": "dataset",
		"Id": "ds_4650feca",
		"Name": "Existing Dataset Name",
		"Owner": {
			"Name": "Owner Name",
			"Email": "owner.email@domain.com"
		},
		"RecordCount": 1,
		"MapCount": 1,
		"Processing": false,
		"ProcessedRecordCount": 0,
		"DateCreated": "2016-02-24T00:00:00",
		"DateModified": "2016-02-24T00:00:00",
        "CreatedBy": "Creator name",
        "ModifiedBy": "Modifier name"
	}, {
		"Object": "dataset",
		"Id": "ds_1ec85d24",
		"Name": "New Dataset",
		"Owner": {
			"Name": "Owner Name",
			"Email": "owner.email@domain.com"
		},
		"RecordCount": 2,
		"MapCount": 1,
		"Processing": false,
		"ProcessedRecordCount": 0,
		"DateCreated": "2016-06-24T00:00:00",
		"DateModified": "2016-06-24T00:00:00",
        "CreatedBy": "Creator name",
        "ModifiedBy": "Modifier name"
	}],
	"Permission": "Full",
	"Owner": {
		"Name": "Owner Name",
		"Email": "owner.email@domain.com"
	},
	"Type": "Self",
	"DateCreated": "2016-03-11T00:00:00",
    "DateModified": "2016-02-24T00:00:00"
}

Update a Map

Updates the specified map by setting the values of parameters passed. The request accepts mostly the same arguments as the map creation call.

Arguments

Argument	Required	Description
`id`	required	The id of the map which needs to be updated.
`name`	optional	The name of the map that needs to be updated.
`datasets`	optional	List of datasets that need to be added to map. The list can contain existing datasets or new datasets. For existing datasets, just provide the id of the dataset. For new dataset, see CREATE A DATASET section for required and optional field.
`IsPublic`	optional	If true, the map will be accessible publicly using MapUrl. Default is false

Returns

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

Definition

PUT https://api.mapline.com/v1/maps/map_7d099a35

Example Request Object

{
	"Name": "New Map Name",
	"IsPublic": "false",
	"Datasets": [{
		"Id": "ds_4650feca"
	}]
}

Example Response Object

{
	"Object": "map",
	"Id": "map_7d099a35",
	"Name": "New Map Name",
	"IsPublic": "false",
	"MapUrl": "https://app.mapline.com/maps/123456",
	"DatasetCount": 1,
	"Datasets": [{
		"Object": "dataset",
		"Id": "ds_4650feca",
		"Name": "Existing Dataset Name",
		"Owner": {
			"Name": "Owner Name",
			"Email": "owner.email@domain.com"
		},
		"RecordCount": 1,
		"MapCount": 1,
		"Processing": false,
		"ProcessedRecordCount": 0,
		"DateCreated": "2016-02-24T00:00:00",
		"DateModified": "2016-02-24T00:00:00",
        "CreatedBy": "Creator name",
        "ModifiedBy": "Modifier name"
	}],
	"Permission": "Full",
	"Owner": {
		"Name": "Owner Name",
		"Email": "owner.email@domain.com"
	},
	"Type": "Self",
	"DateCreated": "2016-03-11T00:00:00",
    "DateModified": "2016-02-24T00:00:00"
}

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_64fedf4f

Example Response Object

{
	"Object": "map",
	"Id": "map_64fedf4f",
	"Name": "territory test",
	"IsPublic": "false",
	"DatasetCount": 1,
	"Datasets": [{
		"Object": "dataset",
		"Id": "ds_4650feca",
		"Name": "Existing Dataset Name",
		"Owner": {
			"Name": "Owner Name",
			"Email": "owner.email@domain.com"
		},
		"RecordCount": 1,
		"MapCount": 1,
		"Processing": false,
		"ProcessedRecordCount": 0,
		"DateCreated": "2016-02-24T00:00:00",
		"DateModified": "2016-02-24T00:00:00",
        "CreatedBy": "Creator name",
        "ModifiedBy": "Modifier name"
	}],
	"Permission": "Full",
	"Owner": {
		"Name": "Owner Name",
		"Email": "owner.email@domain.com"
	},
	"Type": "Self",
	"DateCreated": "2016-03-11T00:00:00",
    "DateModified": "2016-02-24T00:00:00"
}

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 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_7d099a35",
		"Name": "Map 1",
		"DatasetCount": 0,
		"Permission": "Full",
		"Owner": {
			"Name": "Owner Name",
			"Email": "ownername@domain.com"
		},
		"Type": "Self",
		"DateCreated": "2015-06-24T00:00:00",
        "DateModified": "2016-02-24T00:00:00"
	}, {
		"Object": "map",
		"Id": "map_a6fe2e9",
		"Name": "Map 2",
		"DatasetCount": 0,
		"Permission": "Full",
		"Owner": {
			"Name": "Owner Name",
			"Email": "ownername@domain.com"
		},
		"Type": "Self",
		"DateCreated": "2015-06-24T00:00:00",
        "DateModified": "2016-02-24T00:00:00"
	}]
}

PUBLISHED MAP
Publish Settings Object
There is a Publish Settings object within each map, which allows the user to configure different settings when the map is made public and is viewed via the PublicUrl property.
Attributes
Attribute Type Description
ShowSidebar boolean This setting determines whether the sidebar will be shown or not when the map is viewed via the PublicUrl. Default is 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,
}
```

Attribute	Type	Description
`ShowSidebar`	boolean	This setting determines whether the sidebar will be shown or not when the map is viewed via the PublicUrl. Default is false.

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

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.

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, User or Billing Admin)
`CanAccessFinance`	boolean	If true, user has access to invoices.
`PreferredDistanceUnit`	string	User preferred distance unit (Miles, Kilometers, Yards, or Meters). Default is “Miles”.
`DateCreated`	timestamp	Date when 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, 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"
	}]
}

DISTANCE GRID

Distance Grid calculates distance between each location of a source dataset with each location of the destination dataset.

Get Distance Grid

Generate and return a distance grid between locations of two datasets, in comma-separated-values(csv) format. The csv will be compressed (zip) to save space

Arguments

Argument	Required	Description
`Source Id`	Required	The id of source dataset.
`Destination Id`	Required	The id of destination dataset.
`unit`	Optional	Distance unit(Meter, Kilometer, Mile, Yard, Feet) in which the distances between locations will be calculated. If not provided then it will pick from your preferred distance unit(default:Mile).

Returns

A compressed zip file containing the generated distance grid csv file.

A distance grid csv file looks like this:

Download a sample zipped file.

Definition

GET https://api.mapline.com/v1/distancegrid?sourceId=ds_1620da92&destinationId=ds_22c31e79&unit=Kilometer

Mapline API Documentation

INTRODUCTION

API KEYS

ADD API KEY

AUTHENTICATION

AUTHORIZATION

ERRORS

The Error Object

Attributes

HTTP Response Codes

Errors

USAGE LIMITS

LIST

The List Object

Attributes

OWNER

The Owner Object

Attributes

PERMISSION

The Permission Object

Attributes

DATASET

The Dataset Object

Attritubes

Create a Dataset

Arguments

Returns

Definition

Example Request Object

Example Response Object

Retrieve a Dataset

Arguments

Returns

Definition

Example Response Object

Replace a Dataset

Arguments

Returns

Definition

Example Request Object

Example Response Object

Delete a Dataset

Arguments

Returns

Definition

Example Response Object

List All Datasets

Returns

Definition

Example Response Object

HEADERS

Header Object

Attritubes

RECORD

The Record Object

Attritubes

Create a Record

Arguments

Returns

Definition

Example Request Object

Example Response Object

Retrieve a Record

Arguments

Returns

Definition

Example Response Object

Update a Record’s Information

Arguments

Returns

Definition

Example Request Object

Example Response Object

Delete a Record

Arguments

Returns

Definition

Example Response Object

MAP

The Map Object