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.
  • 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
  • OWNERSHIP TYPE

    OWNERSHIP TYPE object provides enumeration value about the ownership of map or dataset objects.

    The Ownership Type Object

    Attributes

    Attribute Type Description
    Type string The enumeration value. The possible values are Self Account Shared
  • 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 collection of string Collection of 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 Collection of headers 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": [
    		"NAME",
    		"POSTAL CODE",
    		"SALES"
    	],
    	"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": [
    		"NAME",
    		"POSTAL CODE",
    		"SALES"
    	],
    	"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
    Name optional New name of dataset if you would like to change it's existing name.
    Id required ID of the dataset to be replaced.
    Headers required Headers for the dataset fields.
    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/datasets/ds_12499c73

    Example Request Object

    {
    	"Name": "Test Dataset",
    	"Id": "ds_12499c73",
    	"Headers":[{
    		"Name":"NAME",
    		"Type":0,
    		"Ordinal":0
    		},{
    		"Name":"POSTAL CODE",
    		"Type":0,
    		"Ordinal":1
    		},{
    		"Name":"SALES",
    		"Type":0,
    		"Ordinal":2
    	}],
    	"Records": [{
    		"Values": [
    			"Mike",
    			"01005",
    			"$290"]
    		},{
    		"Values": [
    			"Jim",
    			"01106",
    			"$452"],
    		}
    }

    Example Response Object

    {
    	"Object":"dataset",
    	"Id":"ds_1b2aef6d",
    	"Name":"Test Dataset",
    	"Headers":[{
    		"Name":"NAME",
    		"Type":0,
    		"Ordinal":0
    		},{
    		"Name":"POSTAL CODE",
    		"Type":1,
    		"Ordinal":1
    		},{
    		"Name":"SALES",
    		"Type":0,
    		"Ordinal":2
    		}],
    	"Owner":{"Name":"Owner Name","Email":"owner.email@domain.com"},
    	"Permission":"None",
    	"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"
    	}]
    }
  • 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 dataset 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

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

    Example Request Object

    {
    	"Id": "map_7d099a35",
    	"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,
    }
    
  •   FILTER

    Filter objects can be applied to different datasets within a map. The user can configure a set of filter objects by providing both the map id and the dataset id. The user can specify one filter object per column of a dataset in a map, however, the user can specify multiple filtering criteria within one filter. For example, if the user has a dataset containing the details of his employees in different cities and wants only the details of his employees living in Chicago, Boston and New York and between the age 30 to 50, then he needs to create 2 filters - one for the column City, and another for the column Age, and his filter would look like "where City Includes Chicago, Boston, New York AND 'Age Greater Than 30 AND Less Than 50'". Here "City" Includes "Chicago, Boston, New York" and "Age Greater Than 30 AND Less Than 50" are the 2 filters, and the latter filter contains 2 filtering criteria, "Greater Than 30" and "Less Than 50" joined together by an AND condition. So, for a particular dataset on a map, the user can configure multiple filters, each having multiple filtering criteria.

    Filter Object

    Attributes

    Attribute Type Description
    Id string The id of the filter.
    Header string Column header of the dataset on which this filter is applied.
    Ordinal integer The ordinal position of the column header on which this filter is applied (useful in case you have more than one columns with the same header name). Either the header or the ordinal must be specified while creating the filter. If both are present, the ordinal will take precedence over the header.
    FilterCriteria list, FilterCriteria object List of filtering criteria for this particular header.

    Create Filter(s)

    Create a filter for a particular map id and a dataset id. If there are already filters existing for this map and dataset, then this filter will be added to the list of existing filters. However, if there is a filter existing for a particular header, and the incoming request also contains a filter to the same header, then an error would be thrown.

    Arguments

    Argument Required Description
    Map Id required The id of the map.
    Dataset Id required The id of the dataset.
    Header required if ordinal is not specified The column header of the dataset on whose values the filters will be applied.
    Ordinal required if header is not specified The column ordinal value of the dataset on whose values the filters will be applied.
    FilterCriteria required, List,FilterCriteria objects List of filtering criteria which needs to be applied to the values of the column specified by the header or the ordinal field.

    Returns

    The full list of filters applied to the particular map and dataset.

    Definition

    POST https://api.mapline.com/maps/map_e1b91e6/datasets/ds_4e810b92/filters

    Example Request Object

    [{
        "Header": "CITY",
        "FilterCriteria": [
          {
            "Operation": "Includes",
            "Value": [
              "New York",
              "Boston",
              "Chicago"
            ]
          }
        ]
      },
      {
        "Header": "AGE",
        "FilterCriteria": [
          {
            "Operation": "GreaterThan",
            "Value": "30"
          },
          {
            "Condition": "And",
            "Operation": "LessThan",
            "Value": "50"
          }
        ]
      }]

    Example Response Object

    [
      {
        "Id": "flt_66767773",
        "Header": "CITY",
        "Ordinal": 2,
        "FilterCriteria": [
          {
            "Operation": "Includes",
            "Value": [
              "New York",
              "Boston",
              "Chicago"
            ]
          }
        ]
      },
      {
        "Id": "flt_d0aba5a",
        "Header": "AGE",
        "Ordinal": 15,
        "FilterCriteria": [
          {
            "Operation": "GreaterThan",
            "Value": "30"
          },
          {
            "Condition": "And",
            "Operation": "LessThan",
            "Value": "50"
          }
        ]
      }
    ]

    Replace Filters

    Replaces the entire set of filters for the particular map and datasets.

    Arguments

    Argument Required Description
    Map Id required The id of the map.
    Dataset Id required The id of the dataset.
    Header required if ordinal is not specified The column header of the dataset on whose values the filters will be applied.
    Ordinal required if header is not specified The column ordinal value of the dataset on whose values the filters will be applied.
    FilterCriteria required, List,FilterCriteria objects List of filtering criteria which needs to be applied to the values of the column specified by the header or the ordinal field.

    Returns

    The replaced list of filters applied to the particular map and dataset.

    Definition

    PUT https://api.mapline.com/maps/map_e1b91e6/datasets/ds_4e810b92/filters

    Example Request Object

    [{
        "Header": "STATE",
        "FilterCriteria": [
          {
            "Operation": "Includes",
            "Value": [
              "Utah",
              "Illinois",
              "Ohio"
            ]
          }
        ]
      },
      {
        "Header": "SEGMENT",
        "FilterCriteria": [
          {
            "Operation": "Equal",
            "Value": "Toys"
          },
          {
            "Condition": "OR",
            "Operation": "Equal",
            "Value": "Baby Products"
          }
        ]
      }]

    Example Response Object

    [
      {
        "Id": "flt_66767773",
        "Header": "CITY",
        "Ordinal": 2,
        "FilterCriteria": [
          {
            "Operation": "Includes",
            "Value": [
              "Utah",
              "Illinois",
              "Ohio"
            ]
          }
        ]
      },
      {
        "Id": "flt_d0aba5a",
        "Header": "SEGMENT",
        "Ordinal": 20,
        "FilterCriteria": [
          {
            "Operation": "Equal",
            "Value": "Toys"
          },
          {
            "Condition": "OR",
            "Operation": "Equal,
            "Value": "Baby Products"
          }
        ]
      }
    ]

    Retrieve a Single Filter

    Gets a single filter, given the filter id along with the map and dataset id.

    Arguments

    Argument Required Description
    Map Id required The id of the map.
    Dataset Id required The id of the dataset.
    Filter Id required The id of the filter.

    Returns

    The details of the filter specified by the id.

    Definition

    GET https://api.mapline.com/maps/map_e1b91e6/datasets/ds_4e810b92/filters/flt_66767773

    Example Response Object

    {
      "Id": "flt_66767773",
      "Header": "CITY",
      "Ordinal": 2,
      "FilterCriteria": [
        {
          "Operation": "Includes",
          "Value": [
            "New York",
            "Boston",
            "Chicago"
          ]
        }
      ]
    }

    Edit Filter

    Edit the filtering criteria of a particular filter.

    Arguments

    Argument Required Description
    Map Id required The id of the map.
    Dataset Id required The id of the dataset.
    Filter Id required The id of the filter.
    Header required if ordinal is not specified The column header of the dataset on whose values the filters will be applied.
    Ordinal required if header is not specified The column ordinal value of the dataset on whose values the filters will be applied.
    FilterCriteria required, List,FilterCriteria objects List of filtering criteria which needs to be applied to the values of the column specified by the header or the ordinal field.

    Returns

    The details of the modified filter.

    Definition

    PUT https://api.mapline.com/maps/map_e1b91e6/datasets/ds_4e810b92/filters/flt_66767773

    Example Request Object

    {
      "Header": "CITY",
      "FilterCriteria": [
        {
          "Operation": "Excludes",
          "Value": [
            "Dacula",
            "Decatur"
          ]
        }
      ]
    }

    Example Response Object

    {
      "Id": "flt_66767773",
      "Header": "CITY",
      "Ordinal": 2,
      "FilterCriteria": [
        {
          "Operation": "Excludes",
          "Value": [
            "Dacula",
            "Decatur"
          ]
        }
      ]
    }

    Delete a Single Filter

    Edit the filtering criteria of a particular filter.

    Arguments

    Argument Required Description
    Map Id required The id of the map.
    Dataset Id required The id of the dataset.
    Filter Id required The id of the filter.

    Returns

    If the filter id is not available, this call returns an error. Else, it silently deletes the specified filter.

    Definition

    DELETE https://api.mapline.com/maps/map_e1b91e6/datasets/ds_4e810b92/filters/flt_66767773

    Delete All Filters

    Edit the filtering criteria of a particular filter.

    Arguments

    Argument Required Description
    Map Id required The id of the map.
    Dataset Id required The id of the dataset.

    Returns

    If no filters are available, this call returns an error. Else, it silently deletes all the filters for the particular map and dataset.

    Definition

    DELETE https://api.mapline.com/maps/map_e1b91e6/datasets/ds_4e810b92/filters
  •     FILTER CRITERIA

    The FilterCriteria object allows you to define the components of a filter. One or more FilterCriteria object(s) are associated with a particular filter.

    FilterCriteria Object

    The FilterCriteria object allows you to define the components of a filter. One or more FilterCriteria object(s) are associated with a particular filter.

    Attributes

    Attribute Type Description
    Condition Enumeration
    (optional).
    The join condition for this particular filtering criteria. Allowed values are:
    AND
    OR
    Also, the user can skip this attribute if the filter consists of a single filtering criteria or if this filtering criteria is the first one of the list of filtering criteria.
    Operation Enumeration The particular operation of the filtering criteria. Allowed values for non numeric values are:
    Equal,
    NotEqual,
    Contain,
    NotContain,
    BeginWith,
    EndWith,
    Includes,
    Excludes.
    And allowed values for numeric values are:
    Equal,
    NotEqual,
    Contain,
    GreaterThan,
    GreaterThanEqual,
    LessThan,
    LessThanEqual,
    Includes,
    Excludes.
    Value string/list of strings The value(s) of the dataset columns against which the operation would be applied. If Includes or Excludes operation is specified, multiple values are allowed. Otherwise, a single value is allowed.
  • 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"
    	}]
    }
The easiest mapping software on the planet
Copyright Mapline®
Support: (800) 969-1454