API Documentation

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 Enterprise 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.
    has_more 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
  • LOCATION

    Location object provides information about a single location within a dataset associated with your account.

    The Location Object

    Attributes

    Attribute Type Description
    id string
    object string, value is “location”
    headers collection of strings Collection of header names associated with the location. If location is associated with a dataset the header information is provided once as part of dataset object.
    values collection of string Collection of values associated with headers in the same order.
    date_created timestamp Date when location is first created.
    date_modified timestamp Date when location was last modified.
  • 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.
    locations list, location object List of all locations associated with the dataset.
    location_count integer Count of locations associated with the dataset.
    maps list, map object List of all maps where this dataset is added as a layer.
    map_count 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 locations.
    processed_location_count integer If processing is true, it will return the number of locations already processed (geocoded).
    date_created timestamp Date when dataset is first created.
    date_modified timestamp Date when 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.
    locations list, required List of all locations 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/datasets

    Example Request Object

    {
    	"name": "Test Dataset",
    	"headers": [
    		"NAME",
    		"POSTAL CODE",
    		"SALES"
    	],
    	"locations": [{
    		"id": "loc_31cdaa92",
    		"values": [
    			"Mike",
    			"01005",
    			"$290"
    		],
    		"error": false,
    		"date_created": "2015-06-24T00:00:00",
    		"date_modified": "0001-01-01T00:00:00"
    	}, {
    		"id": "loc_5ce1ee7d",
    		"values": [
    			"John",
    			"01010",
    			"$180"
    		],
    		"error": false,
    		"date_created": "2015-06-24T00:00:00",
    		"date_modified": "0001-01-01T00:00:00"
    	}]
    }

    Example Response Object

    {
    	"object": "dataset",
    	"id": "ds_249740e8",
    	"name": "Test Dataset",
    	"headers": [
    		"NAME",
    		"POSTAL CODE",
    		"SALES"
    	],
    	"locations": [{
    		"id": "loc_31cdaa92",
    		"values": [
    			"Mike",
    			"01005",
    			"$290"
    		],
    		"error": false,
    		"date_created": "2015-06-24T00:00:00",
    		"date_modified": "2015-06-24T00:00:00"
    	}, {
    		"id": "loc_5ce1ee7d",
    		"values": [
    			"John",
    			"01010",
    			"$180"
    		],
    		"error": false,
    		"date_created": "2015-06-24T00:00:00",
    		"date_modified": "2015-06-24T00:00:00"
    	}],
    	"owner": {
    		"name": "Owner Name",
    		"email": "owneremail@domain.com"
    	},
    	"location_count": 2,
    	"map_count": 0,
    	"processing": false,
    	"processed_location_count": 0,
    	"cluster_density": false,
    	"date_created": "2015-06-24T00:00:00",
    	"date_modified": "2015-06-24T00:00:00"
    }

    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/datasets/ds_249740e8

    Example Response Object

    {
    	"object": "dataset",
    	"id": "ds_249740e8",
    	"name": "Test Dataset",
    	"headers": [
    		"NAME",
    		"POSTAL CODE",
    		"SALES"
    	],
    	"locations": [{
    		"id": "loc_31cdaa92",
    		"values": [
    			"Mike",
    			"01005",
    			"$290"
    		],
    		"error": false,
    		"date_created": "2015-06-24T00:00:00",
    		"date_modified": "0001-01-01T00:00:00"
    	}, {
    		"id": "loc_5ce1ee7d",
    		"values": [
    			"John",
    			"01010",
    			"$180"
    		],
    		"error": false,
    		"date_created": "2015-06-24T00:00:00",
    		"date_modified": "0001-01-01T00:00:00"
    	}],
    	"owner": {
    		"name": "Owner Name",
    		"email": "owneremail@domain.com"
    	},
    	"location_count": 2,
    	"map_count": 0,
    	"processing": false,
    	"processed_location_count": 0,
    	"cluster_density": false,
    	"date_created": "2015-06-24T00:00:00",
    	"date_modified": "2015-06-24T00:00:00"
    }

    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/datasets/ds_249740e8

    Example Response Object

    {
    	"deleted": "true",
    	"id": "ds_249740e8"
    }

    List All Datasets

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

    Returns

    Returns a list object containing all your datasets.

    Definition

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

    Example Response Object

    {
    	"object": "list",
    	"has_more": false,
    	"data": [{
    		"object": "dataset",
    		"id": "ds_249740ea",
    		"name": "Dataset Name",
    		"owner": {
    			"name": "Owner Name",
    			"email": "owner.email@domain.com"
    		},
    		"location_count": 248,
    		"map_count": 0,
    		"processing": false,
    		"processed_location_count": 0,
    		"date_created": "2015-06-24T00:00:00",
    		"date_modified": "2015-06-24T00:00:00"
    	}, {
    		"object": "dataset",
    		"id": "ds_33ab83d1",
    		"name": "Dataset 2 Name",
    		"owner": {
    			"name": "Owner Name",
    			"email": "owner.email@domain.com"
    		},
    		"location_count": 523,
    		"map_count": 0,
    		"processing": false,
    		"processed_location_count": 0,
    		"date_created": "2015-06-24T00:00:00",
    		"date_modified": "2015-06-24T00:00:00"
    	}]
    }
  • 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.
    dataset_count integer Count of user datasets associated with the map.
    is_public boolean If true, the map can be accessible using public_url.
    map_url string Url to access map.
    public_url string URL access to the map as public read only. Available only when is_public 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.
    date_created timestamp Date when dataset is first created.
    date_modified timestamp 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.
    is_public optional If true, the map will be accessible publicly using public_url. 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/maps

    Example Request Object

    {
    	"name": "New Map Name",
    	"is_public": "true",
    	"datasets": [{
    		"id": "ds_4650feca"
    	}, {
    		"name": "new dataset",
    		"locations": [{
    			"values": [
    				"location 1 Name",
    				"location 1 Address",
    				"location 1 Sales Data"
    			]
    		}, {
    			"values": [
    				"location 2 Name",
    				"location 2 Address",
    				"location 2 Sales Data"
    			]
    		}],
    		"headers": [
    			"NAME",
    			"ADDRESS",
    			"SALES DATA"
    		]
    	}]
    }

    Example Response Object

    {
    	"object": "map",
    	"id": "map_64fedf4f",
    	"name": "territory test",
    	"is_public": "true",
    	"map_url": "https://app.mapline.com/maps/123456",
    	"public_url": "https://app.mapline.com/maps/123456/asdwse2ismasmdssadskd/true",
    	"dataset_count": 2,
    	"datasets": [{
    		"object": "dataset",
    		"id": "ds_4650feca",
    		"name": "Existing Dataset Name",
    		"owner": {
    			"name": "Owner Name",
    			"email": "owner.email@domain.com"
    		},
    		"location_count": 1,
    		"map_count": 1,
    		"processing": false,
    		"processed_location_count": 0,
    		"date_created": "2016-02-24T00:00:00",
    		"date_modified": "2016-02-24T00:00:00"
    	}, {
    		"object": "dataset",
    		"id": "ds_1ec85d24",
    		"name": "New Dataset",
    		"owner": {
    			"name": "Owner Name",
    			"email": "owner.email@domain.com"
    		},
    		"location_count": 2,
    		"map_count": 1,
    		"processing": false,
    		"processed_location_count": 0,
    		"date_created": "2016-06-24T00:00:00",
    		"date_modified": "2016-06-24T00:00:00"
    	}],
    	"permission": "Full",
    	"owner": {
    		"name": "Owner Name",
    		"email": "owner.email@domain.com"
    	},
    	"type": "Self",
    	"date_created": "2016-03-11T00: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.
    is_public optional If true, the map will be accessible publicly using map_url. 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/maps

    Example Request Object

    {
    	"id": "map_7d099a35",
    	"name": "New Map Name",
    	"is_public": "false",
    	"datasets": [{
    		"id": "ds_4650feca"
    	}]
    }

    Example Response Object

    {
    	"object": "map",
    	"id": "map_7d099a35",
    	"name": "New Map Name",
    	"is_public": "false",
    	"map_url": "https://app.mapline.com/maps/123456",
    	"dataset_count": 1,
    	"datasets": [{
    		"object": "dataset",
    		"id": "ds_4650feca",
    		"name": "Existing Dataset Name",
    		"owner": {
    			"name": "Owner Name",
    			"email": "owner.email@domain.com"
    		},
    		"location_count": 1,
    		"map_count": 1,
    		"processing": false,
    		"processed_location_count": 0,
    		"date_created": "2016-02-24T00:00:00",
    		"date_modified": "2016-02-24T00:00:00"
    	}],
    	"permission": "Full",
    	"owner": {
    		"name": "Owner Name",
    		"email": "owner.email@domain.com"
    	},
    	"type": "Self",
    	"date_created": "2016-03-11T00: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/maps/map_64fedf4f

    Example Response Object

    {
    	"object": "map",
    	"id": "map_64fedf4f",
    	"name": "territory test",
    	"is_public": "false",
    	"dataset_count": 1,
    	"datasets": [{
    		"object": "dataset",
    		"id": "ds_4650feca",
    		"name": "Existing Dataset Name",
    		"owner": {
    			"name": "Owner Name",
    			"email": "owner.email@domain.com"
    		},
    		"location_count": 1,
    		"map_count": 1,
    		"processing": false,
    		"processed_location_count": 0,
    		"date_created": "2016-02-24T00:00:00",
    		"date_modified": "2016-02-24T00:00:00"
    	}],
    	"permission": "Full",
    	"owner": {
    		"name": "Owner Name",
    		"email": "owner.email@domain.com"
    	},
    	"type": "Self",
    	"date_created": "2016-03-11T00: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/maps/map_64fedf4f

    Example Response Object

    {
    	"deleted": "true",
    	"id": "map_64fedf4"
    }

    List All Maps

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

    Returns

    Returns a list object containing all your maps.

    Definition

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

    Example Response Object

    {
    	"object": "list",
    	"has_more": false,
    	"data": [{
    		"object": "map",
    		"id": "map_7d099a35",
    		"name": "Map 1",
    		"dataset_count": 0,
    		"permission": "Full",
    		"owner": {
    			"name": "Owner Name",
    			"email": "ownername@domain.com"
    		},
    		"type": "Self",
    		"date_created": "2015-06-24T00:00:00"
    	}, {
    		"object": "map",
    		"id": "map_a6fe2e9",
    		"name": "Map 2",
    		"dataset_count": 0,
    		"permission": "Full",
    		"owner": {
    			"name": "Owner Name",
    			"email": "ownername@domain.com"
    		},
    		"type": "Self",
    		"date_created": "2015-06-24T00:00:00"
    	}]
    }
  • 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)
    can_access_finance boolean If true, user has access to invoices.
    preferred_distance_unit string User preferred distance unit (Miles, Kilometers, Yards, or Meters). Default is “Miles”.
    date_created timestamp Date when user was created.
    date_modified timestamp Date when user was last modified.

    Create a User

    Creates a new dataset.

    Arguments

    Argument Required Description
    email required The email of the user.
    name required Name of the user.
    role required Role of the user.
    can_access_finance optional If true, user has access to invoices.
    preferred_distance_unit 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/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",
    	"can_access_finance": true,
    	"preferred_distance_unit": "Miles",
    	"date_created": "2016-06-04T13:08:36.54",
    	"date_modified": "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/users/useremail@domain.com\

    Example Response Object

    {
    	"object": "user",
    	"email": "useremail@domain.com",
    	"name": "User Name",
    	"role": "Owner",
    	"can_access_finance": true,
    	"preferred_distance_unit": "Miles",
    	"date_created": "2016-06-04T13:08:36.54",
    	"date_modified": "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/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/users

    Example Response Object

    {
    	"object": "list",
    	"has_more": false,
    	"data": [{
    		"object": "user",
    		"email": "user1email@domain.com",
    		"name": "User1 Name",
    		"role": "Owner",
    		"can_access_finance": true,
    		"preferred_distance_unit": "Meters",
    		"date_created": "2015-06-04T13:08:36.54",
    		"date_modified": "2015-07-01T19:38:13.047"
    	}, {
    		"object": "user",
    		"email": "user2email@domain.com",
    		"name": "User2 Email",
    		"role": "Administrator",
    		"can_access_finance": false,
    		"preferred_distance_unit": "Meters",
    		"date_created": "2016-01-13T13:44:52.697",
    		"date_modified": "2016-01-20T11:26:04.307"
    	}]
    }