Skip to end of metadata
Go to start of metadata

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

ROUTE

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

Create a Route

 

This method is used to create a route, but it should be considered deprecated, since the typical use case is to generate routes via a POST on the …v1.1/routes/reset URL, which will eliminate existing routes and recalculate them.  Routes may only be created via this method on draft floors.

Method

POST

URL

http://map-api.phunware.com/v1.1/routes

Headers

X-Auth (see Security)

Request Body

Required parameters are underlined.

Parameter

Value

Description

startPointId

integer

The ID of the starting point to match routes against.

endPointId

integer

The ID of the ending point to match routes against.

isAccessible

Boolean

Specifies whether this route is considered accessible.

Default value: false

pointIds

string

Comma-separated, ordered list of the points that make up this route.

floorId

integer

The floor that this route is associated with.

data

array

JSON array containing the points, in order, that comprise this route.

{
    "startPointId": <integer>,
    "endPointId": <integer>,
    "isAccessible": <Boolean>,
    "pointIds": <string>,
    "data": <array>
} 

Example Request

POST the following request body to: http://map-api.phunware.com/v1.1/routes

{
    "startPointId": 78757,
    "endPointId": 75759,
    "isAccessible": true,
    "pointIds": "78757,78758,78759",
    "data": 
	[
        <object containing point ID 78757 data>,
        <object containing point ID 78758 data>,
        <object containing point ID 78759 data>
    ]
} 

Response

A successful response will have a 200 status code and a body containing the newly created route's ID:

{
    "data": 
	{
        "id": <integer>
    }
}

See Mapping API Response Handling for error payloads.

Example Response

Example body of successful response:

{
    "data": 
	{
        "id": 10
    }
}

ON THIS PAGE

 

 

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

Retrieve a Route

 

This method is used to retrieve the points that define a route by route ID.

Method

GET

URL

http://map-api.phunware.com/v1.1/routes/[id]

Headers

X-Auth (see Security)

Query Parameters

None

Example Request

GET
http://map-api.phunware.com/v1.1/routes/10

Response

A successful response will have a 200 status code and a body containing an object with route data:

{
    "id": <integer>,
    "name": <string>,
    "startPointId": <integer>,
    "endPointId": <integer>,
    "isAccessible": <Boolean>,
    "pointIds": <string>,
    "status": <integer>,
    "floorId": <integer>,
    "createdAt": <string>,
    "updatedAt": <string>,
    "data": <array>,
    "isDirty": <Boolean>,
    "externalId": <integer>
}

See Mapping API Response Handling for error payloads. 

Example Response

Example body of a successful response:

{
    "id": 10,
    "name": "The Throne Room-STAIRS",
    "startPointId": 78757,
    "endPointId": 78759,
    "isAccessible": true,
    "pointIds": "78757,78758,78759",
    "status": 2,
    "floorId": 17,
    "createdAt": "2014-06-14T12:21:38Z",
    "updatedAt": null,
    "data": 
	[
        <object containing point ID 78757 data>, 
		<object containing point ID 78758 data>, 
		<object containing point ID 78759 data>
    ],
    "isDirty": null,
    "externalId": 10
} 

ON THIS PAGE

 

 

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

Retrieve a Collection of Routes

 

This method is used to retrieve an array of routes that satisfy search criteria.

Method

GET

URL

http://map-api.phunware.com/v1.1/routes

Headers

X-Auth (see Security)

Query Parameters

Required parameters are underlined. While floorId, startPointId and endPointId are marked as required, only one is necessary for a successful request.

Parameter

Value

Description

floorId

integer

The ID of the floor to get the routes for.

startPointId

integer

The ID of the starting point to match routes against.

endPointId

string

The ID of the ending point to match routes against.

isAccessible

Boolean

Specifies whether to return accessible routes only.

includePoints

Boolean

If true, full point data will be returned within the routes that are found. If false, only the IDs of the points will be included in the returned routes. This is for the convenience of callers that prefer a smaller payload in the response body.

limit

integer

Specifies the number of results to return. This is useful for pagination.

Default value: 10

Maximum value: 100

offset

integer

Specifies the number of results to offset. This is useful for pagination.  

Default value: 0

draftStatusstringEither "LIVE" or "DRAFT". Defaults to "LIVE".

Example Query Fragment

{
	"startPointId": 78757, 
	"isAccessible": true, 
	"floorId": 17, 
	"limit": 2
} 

URL-encoded, minified fragment:

%7B%22startPointId%22%3A78757%2C%22isAccessible%22%3Atrue%2C%22floorId%22%3A17%2C%22limit%22%3A2%7D 

Example Request

GET
http://map-api.phunware.com/v1.1/routes?%7B%22startPointId%22%3A78757%2C%22isAccessible%22%3Atrue%2C%22floorId%22%3A17%2C%22limit%22%3A2%7D 

Response

A successful response will have a 200 status code and a body containing an array of routes that satisfy the query parameters:

{
    "data": 
	[
        {
            "id": <integer>,
            "name": <string>,
            "startPointId": <integer>,
            "endPointId": <integer>,
            "isAccessible": <Boolean>,
            "pointIds": <string>,
            "status"<integer>,
            "floorId": <integer>,
            "createdAt": <string>,
            "updatedAt": <string>,
            "data": <string>,
            "externalId": <integer>
        },
        {
            "id": <integer>,
            "name": <string>,
            "startPointId": <integer>,
            "endPointId": <integer>,
            "isAccessible": <Boolean>,
            "pointIds": <string>,
            "status"<integer>,
            "floorId": <integer>,
            "createdAt": <string>,
            "updatedAt": <string>,
            "data": <string>,
            "externalId": <integer>
        },
        ...
    ],
    "pagination": 
	{
        "results": <object>,
        "pages": <object>
    }
}

The "pagination" and "pages" elements of the response body provide information about the number of items found by the search, how many of those have been returned in the payload and whether there are any other pages of results.

If route generation is in progress, a 202 "Accepted" status code will be returned with an empty set of results to indicate that the resource is not currently available. Example response body:

{
    "data": 
	[
        
    ],
    "pagination": 
	{
        "results": 
		{
            "from": <integer>,
            "to": <integer>,
            "total": <integer>
        },
        "pages": 
		{
            "current": <integer>,
            "prev": <integer>,
            "next": <integer>,
            "total": <integer>
        }
    }
}

If route generation fails, a 500-series status code will be returned. See Mapping API Response Handling for error payloads.

Example Response

Example body of a successful response:

{
    "data": 	
	[
        {
            "id": 10,
            "name": "The Throne Room-STAIRS",
            "startPointId": 78757,
            "endPointId": 78759,
            "isAccessible": true,
            "pointIds": "78757,78758,78759",
            "status:"null,
            "floorId": 17,
            "createdAt": "2014-06-14T12:21:38Z",
            "updatedAt": null,
            "data": 
			[
                <object containing point ID 78757 data>,
                <object containing point ID 78758 data>,
                <object containing point ID 78759 data>
            ],
            "externalId": 10
        },
        {
            "id": 11,
            "name": "Beedle's Bomb Shop-RESTROOM",
            "startPointId": 78701,
            "endPointId": 78703,
            "isAccessible": true,
            "pointIds": "78701,78702,78703",
            "status:"null,
            "floorId": 1,
            "createdAt": "2014-06-14T12:21:38Z",
            "updatedAt": null,
            "data": 
			[
                <object containing point ID 78701 data>,
                <object containing point ID 78702 data>,
                <object containing point ID 78703 data>
            ],
            "externalId": 11
        }
    ],
    "pagination": 
	{
        "results": 
		{
            "from": 1,
            "to": 2,
            "total": 2
        },
        "pages": 
		{
            "current": 1,
            "prev": null,
            "next": null,
            "total": 1
        }
    }
} 

ON THIS PAGE

 

 

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

Retrieve a Location's Routes

 

This method is used to retrieve the route from a given [x,y] or [lat,long] location to a POI.

Method

GET

URL

http://map-api.phunware.com/v1.1/routes/getFromLocation

Headers

X-Auth (see Security)

Query Parameters

Required parameters are underlined.

Parameter

Value

Description

floorId

integer

The ID of the floor to get the routes for.

destinationPOI

integer

The ID of the destination POI.

x

decimal

The x-coordinate to find routes from. Either x,y or location information is required.

y

decimal

The y-coordinate to find routes from. Either x,y or location information is required.

location

object

An object containing the latitude and longitude, in decimal degrees, to find routes from. Either x,y or location information is required.

isAccessible

Boolean

Specifies whether to return accessible routes only.

draftStatusstringEither "LIVE" or "DRAFT". Defaults to "LIVE".

Example Query Fragment

Example fragment for [x,y] location:

{
	"x": 230.4,
	"y": 154.1,
	"floorId": 17,
	"destinationPOI": 78759
}

Example fragment for [lat,long] location: 

{
    "location": 
	{
        "latitude": 30.25,
        "longitude": 97.75
    },
    "floorId": 17,
    "destinationPOI": 78759
}

URL-encoded, minified fragment for [x,y] location:

%7B%0A%22x%22%3A230.4%2C%0A%22y%22%3A154.1%2C%0A%22floorId%22%3A17%2C%0A%22destinationPOI%22%3A374131%0A%7D 

URL-encoded, minified fragment for [lat,long] location:

%7B%22location%22%3A%7B%22latitude%22%3A30.25%2C%22longitude%22%3A97.75%7D%2C%22floorId%22%3A1017%2C%22destinationPOI%22%3A374131%7D

Example Request

Example request for [x,y] location:

GET
http://map-api.phunware.com/v1.1/routes/getFromLocation?%7B%0A%22x%22%3A230.4%2C%0A%22y%22%3A154.1%2C%0A%22floorId%22%3A1017%2C%0A%22destinationPOI%22%3A374131%0A%7D 

Example request for [lat,long] location:

GET
http://map-api.phunware.com/v1.1/routes/getFromLocation?%7B%22location%22%3A%7B%22latitude%22%3A30.25%2C%22longitude%22%3A97.75%7D%2C%22floorId%22%3A1017%2C%22destinationPOI%22%3A374131%7D

Response

A successful response will have a 200 status code and a body containing an array of routes.

{
    "data": 
	[
        {
            "id": <integer>,
            "name": <string>,
            "startPointId": <integer>,
            "endPointId": <integer>,
            "isAccessible": <Boolean>,
            "pointIds": <string>"status": <integer>,
            "floorId": <integer>,
            "createdAt": <string>,
            "updatedAt": <string>,
            "data": 
			[
                <point object 1>,
                <point object 2>,
                ...
            ],
            "isDirty": <Boolean>,
            "externalId": <integer>
        }
    ]
} 

See Mapping API Response Handling for error payloads.

Example Response

Example body of a successful response:

{
    "data": 
	[
        {
            "id": 10,
            "name": "The Throne Room-STAIRS",
            "startPointId": 78757,
            "endPointId": 78759,
            "isAccessible": true,
            "pointIds": "78757,78758,78759",
            "status:"null,
            "floorId": 17,
            "createdAt": "2014-06-14T12:21:38Z",
            "updatedAt": null,
            "data": 	
			[
                <object containing point ID 78757 data>,
                <object containing point ID 78758 data>,
                <object containing point ID 78759 data>
            ],
            "isDirty": null,
            "externalId": 10
        },
        {
            "id": 11,
            "name": "Beedle's Bomb Shop-RESTROOM",
            "startPointId": 78701,
            "endPointId": 78703,
            "isAccessible": true,
            "pointIds": "78701,78702,78703",
            "status:"null,
            "floorId": 1,
            "createdAt": "2014-06-14T12:21:38Z",
            "updatedAt": null,
            "data": 
			[
                <object containing point ID 78701 data>,
                <object containing point ID 78702 data>,
                <object containing point ID 78703 data>
            ],
            "isDirty": null,
            "externalId": 11
        }
    ]
} 

ON THIS PAGE

 

 

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

Retrieve a Count of Routes

 

This method is used to retrieve the number of routes that match search criteria.

Method

GET

URL

http://map-api.phunware.com/v1.1/routes/count

Headers

X-Auth (see Security)

Query Parameters

Required parameters are underlined. While floorId, startPointId and endPointId are marked as required, only one is necessary for a successful request.

Parameter

Value

Description

floorId

integer

The ID of the floor to get the routes for.

startPointId

integer

The ID of the starting point to match routes against.

endPointId

string

The ID of the ending point to match routes against.

isAccessible

bool

Specifies whether to return accessible routes only.

draftStatusstringEither "LIVE" or "DRAFT". Defaults to "LIVE".

Example Query Fragment

{
	"startPointId": 78757, "isAccessible": true, "floorId": 17, "limit": 2
} 

URL-encoded, minified fragment:

%7B%22startPointId%22%3A78757%2C%22isAccessible%22%3Atrue%2C%22floorId%22%3A17%2C%22limit%22%3A2%7D

Example Request

GET
http://map-api.phunware.com/v1.1/routes/count?%7B%22startPointId%22%3A78757%2C%22isAccessible%22%3Atrue%2C%22floorId%22%3A17%2C%22limit%22%3A2%7D

Response

A successful response will have a 200 status code and a body like the below:

{
    "data": 
	{
        "count": <integer>
    }
} 

If route generation fails, a 500-series status code will be returned. See Mapping API Response Handling for error payloads. 

Example Response

Example body of a successful response:

{
    "data": 
	{
        "count": 2
    }
} 

If route generation is in progress, a 202 "Accepted" status code will be returned with an empty set of results to indicate that the resource is not currently available. Example response body:

{
    "data": [],
    "pagination": 
	{
        "results": 
		{
            "from": 0,
            "to": 0,
            "total": 0
        },
        "pages": 
		{
            "current": 1,
            "prev": null,
            "next": null,
            "total": 1
        }
    }
}

ON THIS PAGE

 

 

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

Update a Route

 

Deprecated.  This method is used to update an existing route , but it should be considered deprecated, since the typical use case is to generate routes via a POST on the …v1.1/routes/reset URL, which will eliminate existing routes and recalculate them.  Routes may only be modified via this method on draft floors.

Method

PUT

URL

http://map-api.phunware.com/v1.1/routes/[id]

Headers

X-Auth (see Security)

Request Body

See Mapping API Architecture > PUT Methods & Partial Updates.

Parameter

Value

Description

startPointId

integer

The ID of the starting point of the route.

endPointId

integer

The ID of the ending point of the route.

isAccessible

Boolean

Indicates whether this route is accessible.

pointIds

string

Comma-separated, ordered list of the IDs of the points comprising this route.

floorId

integer

The ID of the floor this route is associated with.

data

array

Array of point objects, in order, that comprise this route.

{
	"endPointId": <integer>,
	"pointIds": <string>,
	"data": <array>
} 

Example Request

PUT the following request body to: http://map-api.phunware.com/v1.1/routes/10

{
    "endPointId": 78758,
    "pointIds": "78757,78758",
    "data": 
	[
        78757,
        78758
    ]
} 

Response

A success response will return a 204 status code with no data in the body of the response. See Mapping API Response Handling for error payloads.

ON THIS PAGE

 

 

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

Delete a Route

 

Deprecated.  This method is used to delete a route , but it should be considered deprecated, since the typical use case is to generate routes via a POST on the …v1.1/routes/reset URL, which will eliminate existing routes and recalculate them.  Routes may only be modified via this method on draft floors.

Method

DELETE

URL

http://map-api.phunware.com/v1.1/routes/[id]

Headers

X-Auth (see Security)

Request Parameters

None

Example Request

DELETE
http://map-api.phunware.com/v1.1/routes/10

Response

A success response will return a 204 status code with no data in the body of the response. See Mapping API Response Handling for error payloads.

ON THIS PAGE

 

 

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

Reset a Building's Routes

 

This method is used to reset a building's routes. It will delete all routes associated with the building and regenerate them.

Method

POST

URL

http://map-api.phunware.com/v1.1/routes/reset

Headers

X-Auth (see Security)

Request Body

Required parameters are underlined.

Parameter

Value

Description

buildingId

integer

The identifier of the building for which to generate routes.

draftStatusstringEither "LIVE" or "DRAFT". Defaults to "LIVE".
{
	"buildingId": <integer>
} 

Example Request

POST the following request body to: http://map-api.phunware.com/v1.1/routes/reset

{
	"buildingId": 6891
} 

Response

A success response will return a 202 status code with no data in the body of the response.

If route generation is in progress, a 423 "Locked" status code will be returned with a response body like the below:

{
    "data": 
	{
        "message": "Resource locked"
    }
} 

To check for reset completion, use the Retrieve a Collection of Routes GET method and specify the floor ID parameter. 

If route generation is still in progress, a 202 response status code will be returned with an empty set of results to indicate that the resource is not currently available. Example response body:

{
    "data": [],
    "pagination": 
	{
        "results": 
		{
            "from": 0,
            "to": 0,
            "total": 0
        },
        "pages": 
		{
            "current": 1,
            "prev": null,
            "next": null,
            "total": 1
        }
    },
    "expiry": "2014-07-23T20:48:03Z"
}

If route generation fails, a 500-series status code will be returned. See Mapping API Response Handling for error payloads. 

ON THIS PAGE

 

 

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

Update a Building's Routes

 

This method is used to update a building's routes. It will not delete the existing routes, but will try to generate any new routes that can be made.

An example scenario where this method would be necessary is if a new point of interest was added to a floor after the last time routes were generated.

Method

POST

URL

http://map-api.phunware.com/v1.1/routes/update

Headers

X-Auth (see Security)

Request Body

Required parameters are underlined.

Parameter

Value

Description

buildingId

integer

The identifier of the building for which to generate routes.

draftStatusstringEither "LIVE" or "DRAFT". Defaults to "LIVE".
{
	"buildingId": <integer>
} 

Example Request

POST the following request body to: http://map-api.phunware.com/v1.1/routes/update

{
	"buildingId": 6891
} 

Response

A success response will return a 202 status code with no data in the body of the response. See Mapping API Response Handling for error payloads.

ON THIS PAGE

 

 

 

A route is an ordered collection of points that connects one point of interest (POI) to another POI.

{
    "id": <integer>,
    "name": <string>,
    "startPointId": <integer>,
    "endPointId": <integer>,
    "isAccessible": <Boolean>,
    "pointIds": <string>,
    "status": <integer>,
    "floorId": <integer>,
    "createdAt": <string>,
    "updatedAt": <string>,
    "data": <array>,
    "isDirty": <Boolean>,
    "externalId": <integer>
}
  • No labels