Setting userWaypoint in API

[+Goldenhawk]

I'd appreciate some help troubleshooting creating user waypoints via the API. No matter what I try it kicks back an error telling me I need to include data that I'm already including. Am I just building the waypoint wrong?

 

Here's my PHP code:

    $json_data = 
    '{
      "userWaypoint":{
        "geocacheCode": "GC12345",
        "description": "Puzzle solution from My Web App",
        "isCorrectedCoordinates": true,
        "coordinates": {
          "latitude": 38.2,
          "longitude": -76.1
        }
      }
    }';
    $APILink="https://staging.api.Groundspeak.com/v1/userwaypoints/?referenceCode=GC12345";
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: bearer ' . $APIToken));
    curl_setopt($ch, CURLOPT_URL, $APILink);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,$json_data);
    $output = curl_exec($ch);
    $responsecode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($responsecode<>200) {
      $response = json_decode($output);
      $statusMessage = $response->statusMessage;
      $errorMessage = $response->errorMessage;
      echo "Status $responsecode: The solution coordinates could not be added on Geocaching.com as a user waypoint; Geocaching said \"$statusMessage\"";
    }

The response from the API is:

    [statusCode] => 400
    [statusMessage] => Bad Request
    [errorMessage] => {"message":"The request is invalid.","modelState":{"userWaypoint.Coordinates":["The Coordinates field is required."],"userWaypoint.GeocacheCode":["The GeocacheCode field is required."]}}
    [uri] => http://partnersapi-staging.Groundspeak.biz/v1/userwaypoints/?referenceCode=GC12JAC

 

[+Goldenhawk]

The API currently says:

Create User Waypoint

This method will create a new user waypoint. It will return the created user waypoint.

Path: /v1/userwaypoints
HTTP Method: POST
Response Type: User Waypoint
Response Codes: 201, 400, 401, 404, 409, 500

 

Parameters

Argument	Type	Example	Required	Description	Default
referenceCode	path	gc25	Yes	the identifier of the geocache	-
userWaypoint	body	UserWaypoint	Yes	user waypoint to create	-

[+Goldenhawk]

And the UserWaypoint format in the API documentation is defined as:

 

UserWaypoint

Fields

Name	Type	Description	Required for Creation	Can Be Updated (By Waypoint Owner)
referenceCode	string	uniquely identifies the user waypoint	No	No
description	string	text about the waypoint	Optional	Yes
isCorrectedCoordinates	bool	whether the user waypoint are corrected coordinates	Yes	Yes
coordinates	Coordinates	latitude and longitude of the waypoint	Yes	Yes
geocacheCode	string	identifier of the related geocache	Yes	No

Example

{
    "referenceCode": "UW167H5Q",
    "description": "Coordinate Override",
    "isCorrectedCoordinates": true,
    "coordinates": {
        "latitude": 0.6489666666666667,
        "longitude": -0.3481166666666667
    },
    "geocacheCode": "GCK25B"
}

[+Corfman Clan]

You're messing up the request URI. You have:

$APILink="https://staging.api.Groundspeak.com/v1/userwaypoints/?referenceCode=GC12345";

But you should have:

$APILink="https://staging.api.Groundspeak.com/v1/userwaypoints/?fields:referenceCode";

Note that you are specifying what is returned to you. The reference code here would be the reference code of the newly added waypoint. That is, you are not specifying what geocache you want to add the waypoint to, that's specified in the waypoint structure you pass in.

[+Goldenhawk]

Thanks for the reply. I tried that but it didn't change anything. Same exact response:

stdClass Object
(
    [statusCode] => 400
    [statusMessage] => Bad Request
    [errorMessage] => {"message":"The request is invalid.","modelState":{"userWaypoint.Coordinates":["The Coordinates field is required."],"userWaypoint.GeocacheCode":["The GeocacheCode field is required."]}}
    [uri] => http://partnersapi-staging.Groundspeak.biz/v1/userwaypoints/?fields:referenceCode
)

Also, note that the API documentation says that referenceCode is required in the path, which (for all the other verbs I've been able to get working) means that you must include it the way I did. You can ALSO specify a returned set of fields as you showed. So I don't think that's what's wrong.

[+Corfman Clan]

First, reference code is more than just a geocache code. There are reference codes for geocaches, geocachers, geocache logs, user waypoints, user lists, etc. The way you included it is not correct. I suggest you play with the swagger and you can see exactly what works and what the response is. I just created and then deleted a user waypoint using the swagger interface. You'll need to enter a valid access token in the upper right of the page:

https://api.Groundspeak.com/api-docs/index#!/UserWaypoints/UserWaypoints_CreateUserWaypoint

https://staging.api.Groundspeak.com/api-docs/index#!/UserWaypoints/UserWaypoints_CreateUserWaypoint

 

[+Goldenhawk]

Can you give me an example, or pointers on what I'm doing wrong? Swagger is cool (never saw it before, and never got any email from Groundspeak about it), but it's not intuitive and doesn't tell you what you're doing wrong.

[+Goldenhawk]

Note that what Swagger shows is NOT the same as what the API documentation says. It's not good when the official documentation differs from reality. The documentation says:

Parameters

Argument	Type	Example	Required	Description	Default
referenceCode	path	gc25	Yes	the identifier of the geocache	-
userWaypoint	body	UserWaypoint	Yes	user waypoint to create	-

 

That information is very explicit that the path should contain something like ?referenceCode=gc25, e.g.

https://staging.api.Groundspeak.com/v1/userwaypoints/?referenceCode=GC12JAC

IN ADDITION to the post fields. But your example and Swagger say otherwise. If I'm working from the API documentation, it should be trustworthy. That's disappointing.

[+Corfman Clan]

Yes, it appears the documentation is messed up in the user waypoints section. I rarely look at that and mostly use the Swagger as that is based on the actual API  declaration. I consider the Swagger a key part of the documentation and it wins over any difference between it and that in https://api.Groundspeak.com/documentation. However, with that said, there may be implementation errors so those things certainly may be questioned with Geocaching HQ. On that line, it wouldn't hurt to let the API team know there are errors with the documentation so they can make corrections.

 

Concerning adding a user waypoint with the Swagger. With the userWaypoint text box empty, click on the example value and it will populate the text box with that. Next, edit the values as you see fit, then click on, Try it out!

 

You'll be able to see what was sent and the response.

[+Corfman Clan]

One other thing, you're checking for a status code = 200. It probably won't be 200, but 201 or even 204. Good luck.

[+Goldenhawk]

Finally got something working - still not sure what changed, maybe some very minor detail of my JSON, but who cares; I won't mess with a working setup.

 

It's incredibly annoying how far off the API documentation things are. When I asked Groundspeak for help this week with getting authorization working, they emailed me the link to the API documentation, but not the Swagger link. So I've been beating my head against a wall with incorrect information, only lucking out once every few hours with some random troubleshooting attempt. Almost like they don't want us to succeed...

 

Thanks again for your pointers.

[+hxdimpf]

I have seen the userWaypoints in the API documentation and following this thread, I was wondering, what role do they play on the website, what's their purpose? Can I create, read, update, delete userWaypoints by using the website or any existing application?

[+Hügh]

On 9/5/2023 at 6:19 PM, hxdimpf said:

Can I create, read, update, delete userWaypoints by using the website

 

No.

 

On 9/5/2023 at 6:19 PM, hxdimpf said:

or any existing application

 

Yes, the Official Geocaching app(s) and some API partners like Cachly support this.

[+hxdimpf]

ok so I'd assume it is within the app's discretion what kind of functionality they build on top of these userWaypoints?