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.

POINT

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 Point

 

This method is used to create a point.  This will create a draft point.  Points may only be created on draft floors.

Method

POST

URL

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

Headers

X-Auth (see Security)

Request Body

Required parameters are underlined.

Parameter

Value

Description

name

string

The name of the point.

poiType

integer

The type of point. See POI TYPES for named types and their associated integer values.

Default: 0

category

string

Describes the kind of point (e.g. "Exhibit", "Shop", "Facilities", etc.).

description

string

A description of this point.

isActive

Boolean

Describes whether the point is active (“true”) or inactive (“false”). A point is typically set to inactive to indicate that it is being edited or is no longer valid.

imageUrl

string

The URL of an image file associated with the point. This image is used by client applications to display banner images.

customIconImageUrl

string

The URL of a custom image to use when displaying an icon for this point. If there is no customImageIconUrl, a standard icon based on the poiType will be used.

x

integer

The x-location of this point.

y

integer

The y-location of this point.

isExit

Boolean

Indicates whether this point is an exit.

isAccessible

Boolean

Indicates whether this point is accessible.

portalId

string

A portal is a point providing access between floors, such as an elevator or stairway. A non-null portalId indicates that this point is a portal.

level

integer

The level of this point.

floorId

integer

The identifier of the floor that this point belongs to.

annotation

string

Information about this point, less than a full description.

zoomLevel

integer

The zoom level of this point.

maxZoomLevel

integer

The maximum zoom level of this point.

buildingId

integer

The identifier of the building that this point belongs to.

metaData

object

Extra data that can be stored with the point.

location

object

An object containing the latitude and longitude of the point, in decimal degrees.

{
    "name": <string>,
    "poiType": <integer>,
    "category": <string>,
    "description": <string>,
    "isActive": <Boolean>,
    "imageUrl": <string>,
    "customIconImageUrl": <string>,
    "x": <integer>,
    "y": <integer>,
    "isExit": <Boolean>,
    "isAccessible": <Boolean>,
    "portalId": <string>,
    "level": <integer>,
    "floorId": <integer>,
    "annotation": <string>,
    "zoomLevel": <integer>,
    "maxZoomLevel": <integer>,
    "buildingId": <integer>,
    "metaData": <object>,
    "location": 
	{
        "latitude": <decimal>,
        "longitude": <decimal>
    }
}

Example Request

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

{
    "name": "The Throne Room",
    "poiType": 2,
    "category": null,
    "description": "Where Zelda sits when not hostage elsewhere.",
    "isActive": true,
    "imageUrl": "http://www.image.com/point.png",
    "customIconImageUrl": "http://www.image.com/throne1.png",
    "x": 43,
    "y": 81,
    "isExit": true,
    "isAccessible": true,
    "portalId": null,
    "level": 1,
    "floorId": 17,
    "annotation": "exit from courtyard",
    "zoomLevel": 1,
    "maxZoomLevel": -1,
    "buildingId": 6891,
    "metaData": null,
    "location": 
	{
        "latitude": 37.12345,
        "longitude": 97.01234
    }
}

Response

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

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

See Mapping API Response Handling for error payloads.

Example Response

Example body of successful response:

{
    "data": 
	{
        "id": 78757
    }
}

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 Point

 

This method is used to retrieve a point by point ID.

Method

GET

URL

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

Headers

X-Auth (see Security)

Query Parameters

Required parameters are underlined. While both "floorId" and "buildingId" are marked as required, either one is sufficient.

Parameter

Value

Description

draftStatus

string

Either "LIVE" or "DRAFT". Defaults to "LIVE".

Example Request

GET
http://map-api.phunware.com/v1.1/points/78757 

Response

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

{
    "id": <integer>,
    "name": <string>,
    "poiType": <integer>,
    "category": <string>,
    "description": <string>,
    "isActive": <Boolean>,
    "imageUrl": <string>,
    "customIconImageUrl": <string>,
    "x": <integer>,
    "y": <integer>,
    "isExit": <Boolean>,
    "isAccessible": <Boolean>,
    "portalId": <string>,
    "level": <integer>,
    "annotation": <string>,
    "zoomLevel": <integer>,
    "maxZoomLevel": <integer>,
    "floorId": <integer>,
    "buildingId": <integer>,
    "metaData": <object>,
    "createdAt": <string>,
    "updatedAt": <string>,
    "location": 
	{
        "latitude": <decimal>,
        "longitude": <decimal>
    },
    "externalId": <integer>
} 

See Mapping API Response Handling for error payloads.

Example Response

Example body of a successful response:

{
    "id": 78757,
    "name": "The Throne Room",
    "poiType": 2,
    "category": null,
    "description": "Where Zelda sits when not hostage elsewhere.",
    "isActive": true,
    "imageUrl": "http://www.image.com/point.png",
    "customIconImageUrl": "http://www.image.com/throne1.png",
    "x": 43,
    "y": 81,
    "isExit": true,
    "isAccessible": true,
    "portalId": null,
    "level": 1,
    "zoomLevel": 2,
    "maxZoomLevel": -1,
    "floorId": 17,
    "buildingId": 6891,
    "annotation": "exit from courtyard",
    "metaData": null,
    "createdAt": "2013-09-04T13:32:55Z",
    "updatedAt": "2013-09-04T13:32:55Z",
    "location": 
	{
        "latitude": 37.12345,
        "longitude": 97.01234
    },
    "externalId": 78757
} 

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 Points by Floor and/or Building

 

This method is used to retrieve an array of points on a floor that satisfy search criteria.

Method

GET

URL

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

Headers

X-Auth (see Security)

Query Parameters

Required parameters are underlined. While both "floorId" and "buildingId" are marked as required, either one is sufficient.

Parameter

Value

Description

floorId

integer

Return points that are on this floor.

buildingId

integer

Return points that are in this building.

filter

object

Object containing an array of valid response body fields. Used to reduce the response payload for each point to only the fields specified in the request.

The "id" field is always returned whether or not it is explicitly specified.

isActiveBooleanDescribes whether to search for active (“true”) or inactive (“false”) points. Both active and inactive points will be retrieved by default. 

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

poiOnlyBoolean
  • If true, returns only points of interest. 
  • If false, returns all points (including waypoints). 

Default value: false

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

Example Query Fragment

Example without filter(s):

{
	"floorId": 17,
	"buildingId": 6891
} 

URL-encoded, minified fragment of example without filter(s):

%7B%22floorId%22%3A17%2C%22buildingId%22%3A6891%7D

Example with filter(s):

{
    "floorId": 17,
    "buildingId": 6891,
    "filter": 
	{
        "include": 
		[
            "name",
            "isAccessible",
            "location"
        ]
    }
}

URL-encoded, minified fragment of example with filter(s):

%7B%22floorId%22%3A17%2C%22buildingId%22%3A6891%22filter%22%3A%7B%22include%22%3A%5B%22name%22%2C%22isAccessible%22%2C%22location%22%5D%7D%7D 

Example Request

Example without filter(s):

GET
http://map-api.phunware.com/v1.1/points?%7B%22floorId%22%3A1%2C%22buildingId%22%3A1%7D

Example with filter(s):

GET
http://map-api.phunware.com/v1.1/points?%7B%22floorId%22%3A17%2C%22buildingId%22%3A6891%22filter%22%3A%7B%22include%22%3A%5B%22name%22%2C%22isAccessible%22%2C%22location%22%5D%7D%7D 

Response

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

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

See Mapping API Response Handling for error payloads.

Example Response

Example body of a successful response without filters (continued on the next page):

{
    "data": 
	[
        {
            "id": 78757,
            "name": "The Throne Room",
            "poiType": 2,
            "category": null,
            "description": "Where Zelda sits when not hostage elsewhere.",
            "isActive": true,
            "imageUrl": "http://www.image.com/point.png",
            "customIconImageUrl": "http://www.image.com/throne1.png",
            "x": 43,
            "y": 81,
            "isExit": true,
            "isAccessible": true,
            "portalId": null,
            "level": 1,
            "annotation": "exit from courtyard",
            "zoomLevel": 2,
            "maxZoomLevel": -1,
            "floorId": 17,
            "buildingId": 6891,
            "metaData": null,
            "createdAt": "2013-09-04T13:32:55Z",
            "updatedAt": "2013-09-04T13:32:55Z",
            "location": 
			{
                "latitude": 37.12345,
                "longitude": 97.01234
            },
            "externalId": 78757
        },
        {
            "id": 78758,
            "name": "Dungeon",
            "poiType": 2,
            "category": null,
            "description": "Where rupees are hidden in jars.",
            "isActive": true,
            "imageUrl": "http://www.image.com/point.png",
            "customIconImageUrl": "http://www.image.com/dungeon1.png",
            "x": 34,
            "y": 18,
            "isExit": true,
            "isAccessible": true,
            "portalId": null,
            "level": 1,
            "annotation": "exit from Great Hall",
            "zoomLevel": 2,
            "maxZoomLevel": -1,
            "floorId": 18,
            "buildingId": 6891,
            "metaData": null,
            "createdAt": "2013-09-04T13:32:55Z",
            "updatedAt": "2013-09-04T13:32:55Z",
            "location": 
			{
                "latitude": 73.12345,
                "longitude": 79.01234
            },
            "externalId": 78758
        }
    ],
	"pagination": 
	{
        "results": 
		{
            "from": 1,
            "to": 2,
            "total": 61
        },
        "pages": 
		{
            "current": 1,
            "prev": null,
            "next": 2,
            "total": 2
        }
    }
} 

Example body of a successful response with filter(s):

{
    "data": 
	[
        {
            "id": 78757,
            "name": "The Throne Room",
            "isAccessible": true,
            "location": 
			{
                "latitude": 37.12345,
                "longitude": 97.01234
            },
            "externalId": 78757
        },
        {
            "id": 78758,
            "name": "Dungeon",
            "isAccessible": true,
            "location": 
			{
                "latitude": 73.12345,
                "longitude": 79.01234
            },
            "externalId": 78758
        }
    ],
	"pagination": 
	{
        "results": 
		{
            "from": 1,
            "to": 2,
            "total": 61
        },
        "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 Count of Points by Floor and/or Building

 

This method is used to retrieve the number of points on a floor that match search criteria.

Method

GET

URL

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

Headers

X-Auth (see Security)

Query Parameters

Required parameters are underlined. While both "floorId" and "buildingId" are marked as required, either one is sufficient. 

Parameter

Value

Description

floorId

integer

Return points that are on this floor.

buildingId

integer

Return points that are in this building.

isActive

boolean

If omitted, get count of points that are either active or inactive.

If true, get count of points that are active.

If false, get count of points that are inactive.

poiOnlyBoolean
  • If true, returns only points of interest. 
  • If false, returns all points (including waypoints). 

Default value: false

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

Example Query Fragment

{
	"floorId": 17,
	"buildingId": 6891
} 

URL-encoded, minified fragment:

%7B%22floorId%22%3A17%2C%22buildingId%22%3A6891%7D 

Example Request

GET
http://map-api.phunware.com/v1.1/points/count?%7B%22floorId%22%3A1%2C%22buildingId%22%3A1%7D 

Response

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

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

See Mapping API Response Handling for error payloads.

Example Response

Example body of a successful response:

{
    "data": 
	{
        "count": 5
    }
} 

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 Point

 

This method is used to update an existing point.   Only draft points (i.e. points that belong to a draft floor) may be modified via this method.

Method

PUT

URL

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

Headers

X-Auth (see Security)

Request Body

See Mapping API Architecture > PUT Methods & Partial Updates.

Parameter

Value

Description

name

string

The name of the point.

poiType

integer

The type of point. See POI TYPES for named types and their associated integer values.

Default: 0

category

string

Describes the kind of point (e.g. "Exhibit", "Shop", "Facilities", etc.).

description

string

A description of this point.

isActive

Boolean

Describes whether the point is active (“true”) or inactive (“false”). A point is typically set to inactive to indicate that it is being edited or is no longer valid.

imageUrl

string

The URL of an image file associated with the point. This image is used by client applications to display banner images.

customIconImageUrl

string

The URL of a custom image to use when displaying an icon for this point. If there is no customImageIconUrl, a standard icon based on the poiType will be used.

x

integer

The x-location of this point.

y

integer

The y-location of this point.

isExit

Boolean

Indicates whether this point is an exit.

isAccessible

Boolean

Indicates whether this point is accessible.

portalId

string

A portal is a point providing access between floors, such as an elevator or stairway. A non-null portalId indicates that this point is a portal.

level

integer

The level of this point.

floorId

integer

The identifier of the floor that this point belongs to.

annotation

string

Information about this point, less than a full description.

zoomLevel

integer

The zoom level of this point.

maxZoomLevel

integer

The maximum zoom level of this point.

buildingId

integer

The identifier of the building that this point belongs to.

metaData

object

Extra data that can be stored with the point.

location

object

An object containing the latitude and longitude of the point, in decimal degrees.

name

string

The name of the point.

{
	"id": <integer>,
	"description": <string>,
	"isActive": <Boolean>
} 

Example Request

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

{
    "id": 78757,
    "description": "Zelda's been kidnapped... again.",
    "isActive": false
}

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 Point 

 

This method is used to delete a point.   Only draft points (i.e. points that belong to a draft floor) may be modified via this method.

Method

DELETE

URL

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

Headers

X-Auth (see Security)

Request Parameters

None

Example Request

DELETE
http://map-api.phunware.com/v1.1/points/78757

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

 

 

 

A point is a specific location on a floor, like a point of interest (POI), waypoint or portal location. 

{
    "id": <integer>,
    "name": <string>,
    "poiType": <integer>,
    "category": <string>,
    "description": <string>,
    "isActive": <Boolean>,
    "imageUrl": <string>,
    "customIconImageUrl": <string>,
    "x": <integer>,
    "y": <integer>,
    "isExit": <Boolean>,
    "isAccessible": <Boolean>,
    "portalId": <string>,
    "level": <integer>,
    "zoomLevel": <integer>,
    "maxZoomLevel": <integer>,
    "floorId": <integer>,
    "buildingId": <integer>,
    "annotation": <string>,
    "metaData": <JSON>,
    "createdAt": <string>,
    "updatedAt": <string>,
    "location": 
	{
        "latitude": <decimal>,
        "longitude": <decimal>
    },
    "externalId": <integer>
}
  • No labels