#Location Shares Endpoint

Our customers can share their units’ and their groups’ location via Location Share Links that can also be used to embed a map on their website.

Share links look like this: https://corvusgps.com/share/vpr3ha

Embeddable code would look like this:

<iframe 
    width="420" 
    height="380" 
    frameborder="0"
    src="https://corvusgps.com/share/b05hcj" 
    >
</iframe>

#List all your shares:

GET https://api.corvusgps.com/v2/location-shares/

{
    "success": "Location Shares has been retrieved successfully!",
    "result": {
        "vpr3ha": {
                "sid": "vpr3ha",
                "uid": 0,
                "did": 5,
                "device": {
                    "did": 1,
                    "name": "Josh",
                    "uniqueID": "0:1",
                    "trackerID": "123456789024680",
                    "deviceType": "evertrack",
                    "deviceCategory": "device",
                    "isActive": 1,
                    "guard": "installed",
                    "humidity": null,
                    "airPressure": null,
                    "temperature": null,
                    "lastBatteryLevel": 100,
                    "lastGPSTimestamp": 1572756668,
                    "lastKnownAddress": "Veterans Blvd, San Francisco, USA",
                    "lastValidLatitude": 37.79926,
                    "lastValidLongitude": -122.46953,
                    "odometerKM": 6088179.63,
                    "groupMember": [
                        1
                    ]
                },
                "name": "ACME Industries - Location of Field Forces",
                "timestamp": 1463587547,
                "expiration": 1512875612,
            },
        "b05hcj": {
                "sid": "b05hcj",
                "uid": 0,
                "gid": 1,
                "group": {
                    "1": {
                        "gid": 1,
                        "name": "ACME Industries - Field Forces",
                        "groupMembers": [
                            1,
                            2,
                            3
                        ],
                        "groupViewers": [
                            4,
                            5,
                            6
                        ]
                    }
                }
                "name": "ACME Industries - Location of Field Forces",
                "timestamp": 1493585127,
                "expiration": "never",
            }
        },
    "resultCount": 2
}

#List a specific individual share:

GET https://api.corvusgps.com/v2/location-shares/vpr3ha

{
    "success": "Location Share has been retrieved successfully!",
    "result": {
        "vpr3ha": {
            "sid": "vpr3ha",
            "uid": 0,
            "did": 5,
            "device": {
                "did": 1,
                "name": "Josh",
                "uniqueID": "0:1",
                "trackerID": "123456789024680",
                "deviceType": "evertrack",
                "deviceCategory": "device",
                "isActive": 1,
                "guard": "installed",
                "humidity": null,
                "airPressure": null,
                "temperature": null,
                "lastBatteryLevel": 100,
                "lastGPSTimestamp": 1572756668,
                "lastKnownAddress": "Veterans Blvd, San Francisco, USA",
                "lastValidLatitude": 37.79926,
                "lastValidLongitude": -122.46953,
                "odometerKM": 6088179.63,
                "groupMember": [
                    1
                ]
            },
            "name": "ACME Industries - Location of Field Forces",
            "timestamp": 1463587547,
            "expiration": 1512875612,
        }
    },
    "resultCount": 1
}

#List a specific group share:

GET https://api.corvusgps.com/v2/location-shares/b05hcj

{
    "success": "Location Share has been retrieved successfully!",
    "result": {
        "b05hcj": {
            "sid": "b05hcj",
            "uid": 0,
            "gid": 1,
            "group": {
                 "1": {
                    "gid": 1,
                    "name": "ACME Industries - Field Forces",
                    "groupMembers": [
                        1,
                        2,
                        3
                    ],
                    "groupViewers": [
                        4,
                        5,
                        6
                    ]
                }
            },
            "name": "ACME Industries - Location of Field Forces",
            "timestamp": 1463587547,
            "expiration": "never",
        }
    },
    "resultCount": 1
}

#Creating a new share

You can create a new share by providing the ID of the group or the device . You can set the expiration three ways:

#(A) Explicitly providing the timestamp (unix epoch) using the expiration field:

POST https://api.corvusgps.com/v2/location-shares/

Parameters:

{
    "did":          "55",
    "name":         "James",
    "expiration":   "1234567890"
}

#(B) Providing the expiration relative to current time using the days/hours/minutes fields:

POST https://api.corvusgps.com/v2/location-shares/

Parameters:

{
    "gid": "66",
    "name": "Jay",
    "days": "3",
    "hours": "2",
    "minutes": "1"
}

#(C) Omitting the expiration altogether so the share will not expire at all

POST https://api.corvusgps.com/v2/location-shares/

Parameters:

{
    "gid":      "66",
    "name":     "Bob" 
}

If everything went well you will get a response like this:

{
    "result": {
        "vpr3ha": {
            "sid": "vpr3ha",
            "uid": 0,
            "did": 55,
            "device": {
                "did": 1,
                "name": "Kevin",
                "uniqueID": "0:1",
                "trackerID": "123456789024680",
                "deviceType": "evertrack",
                "deviceCategory": "device",
                "isActive": 1,
                "guard": "installed",
                "humidity": null,
                "airPressure": null,
                "temperature": null,
                "lastBatteryLevel": 100,
                "lastGPSTimestamp": 1572756668,
                "lastKnownAddress": "Veterans Blvd, San Francisco, USA",
                "lastValidLatitude": 37.79926,
                "lastValidLongitude": -122.46953,
                "odometerKM": 6088179.63,
                "groupMember": [
                    1
                ]
            },
            "name": "Kevin",
            "timestamp": 1572742225,
            "expiration": "never"
        }
    },
    "success": "Location Share has been created successfully!",
    "id": 1,
    "resultCount": 1
}

#Modify an existing share

You can modify an existing share by sending the new values in a PATCH query. Note that only the name and expiration can be changed after their creation.

PATCH https://api.corvusgps.com/v2/location-shares/vpr3ha

Parameters:

{
    "name": "Smith",
    "expiration": 1382942253
}

{
    "success": "Location Share has been modified successfully!",
    "result": [
        "vpr3ha": {
            "sid": "vpr3ha"
            "uid": 0,
            "did": 55,
            "device": {
                "did": 1,
                "name": "Kevin",
                "uniqueID": "0:1",
                "trackerID": ""123456789024680"",
                "deviceType": "evertrack",
                "deviceCategory": "device",
                "isActive": 1,
                "guard": "installed",
                "humidity": null,
                "airPressure": null,
                "temperature": null,
                "lastBatteryLevel": 100,
                "lastGPSTimestamp": 1572756668,
                "lastKnownAddress": "Veterans Blvd, San Francisco, USA",
                "lastValidLatitude": 37.79926,
                "lastValidLongitude": -122.46953,
                "odometerKM": 6088179.63,
                "groupMember": [
                    1
                ]
            },
            "name": "Smith",
            "timestamp": 1382942253,
            "expiration": "never"
        }

    ]
    "resultCount": 1
}

#Delete a Location Share

DELETE https://api.corvusgps.com/v2/location-shares/vpr3ha

{
    "success": "Deleted Successfully!"
}