POST
/
v1
/
cogo
/
generate-metes
curl --request POST \
     --url https://osm.buntinglabs.com/v1/cogo/generate-metes \
     --header "Content-Type: application/json" \
     --data '{
     "api_key": "demo",
     "coordinates": [[-77.037871,38.898545],[-77.037843,38.896174],[-77.036804,38.895375],[-77.035206,38.898545],[-77.037871,38.898545]]
}'

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "properties": {
      "bearing_sexagesimal": "S 0° 31' 35″ E",
      "distance_meters": 263.224,
      "true_bearing_degrees": 179.473
    },
    "geometry": {
      "coordinates": [
        [ -77.037871, 38.898545 ],
        [ -77.037843, 38.896174 ]
      ],
      "type": "LineString"
    }
  }]
}

This API endpoint generates the bearing (cardinal/compass direction) and distance (in meters) between consecutive points in a supplied polygon (GeoJSON).

This endpoint is useful for rendering survey diagrams like this:

​
Request Parameters

​
coordinates
array
required

A sequence of coordinates (single array of [longitude, latitude] points) that will be used to generate the bearing and distance. Similar to the GeoJSON requirement, the coordinates must be closed (the first must equal the last).

Because it is a single sequence (“ring”), it cannot have any holes and cannot be a MultiPolygon. It will have no properties.

Providing at least 6 decimal places is recommended (approximately 11 cm precision). An example sequence of coordinates might look like this, in JSON:

{
  "coordinates": [
    [ -77.03787199, 38.89854538 ],
    [ -77.03784314, 38.89617453 ],
    [ -77.03680463, 38.89537525 ],
    [ -77.03571997, 38.89560426 ],
    [ -77.03521802, 38.89639905 ],
    [ -77.03520648, 38.89854538 ],
    [ -77.03787199, 38.89854538 ]
  ]
}
​
api_key
string
required

Your account’s API key. You can create an API key by registering for an account and copy and paste it from your account dashboard.

​
Response

When features are successfully counted, a 200 OK response will be issued, with Content-Type: application/json. The body will be a FeatureCollection of GeoJSON LineStrings, where each LineString represents a line from the polygon.

Each LineString belongs to a Feature which will have the properties bearing_sexagesimal, true_bearing_degrees, and distance_meters.

​
distance_meters
float

The distance along this line, in meters.

​
true_bearing_degrees
float

This represents the bearing (or azimuth) of the line. This bearing is calculated from true north and has values 0°-360°, where 0° is due north and 90° is due east.

​
bearing_sexagesimal
string

This is a string formatting of true_bearing_degrees that surveyors typically use. It designates the north/south cardinal direction in which to travel and the angle from which one should deviate.

For example, N 21° 25' 15″ E is equivalent to true bearing 21.42. This is sexagesimal (base-60), hence 25/60 ~ 0.42.

In the event of an error, an error response will be issued, usually with a 5xx error code. The error will be JSON-formatted, with an error field describing the cause.

​
error
string

The error message if the extract request parameters were incorrectly formatted.

This response field will not be present if the extract succeeds.

curl --request POST \
     --url https://osm.buntinglabs.com/v1/cogo/generate-metes \
     --header "Content-Type: application/json" \
     --data '{
     "api_key": "demo",
     "coordinates": [[-77.037871,38.898545],[-77.037843,38.896174],[-77.036804,38.895375],[-77.035206,38.898545],[-77.037871,38.898545]]
}'

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "properties": {
      "bearing_sexagesimal": "S 0° 31' 35″ E",
      "distance_meters": 263.224,
      "true_bearing_degrees": 179.473
    },
    "geometry": {
      "coordinates": [
        [ -77.037871, 38.898545 ],
        [ -77.037843, 38.896174 ]
      ],
      "type": "LineString"
    }
  }]
}