Protected Areas Tutorial

This tutorial provides a step-by-step guide on how to validate whether a location intersects with protected areas using the Vantage Protected-Areas API.

In this guide, you will learn how to:

Authenticate with the API
Submit registered plot IDs for protected area validation
Submit raw geometries (GeoJSON) for validation
Retrieve details of intersecting protected areas

Authentication

All API requests require authentication via bearer token.

To authenticate, use the login endpoint:

curl --location -X POST 'https://vantage.open-atlas.com/login' \
--user 'user:password'

This will return a short-lived token:

{
  "token": "xxx…xxx"
}

We recommend exporting it to your environment:

export YOUR_BEARER_TOKEN="xxx…xxx"

Use this token in the Authorization header for all subsequent requests.

Run a Protected Area Check

You can run a protected area check for one or more registered plots (using plot_ids), raw geometries (GeoJSON), or both in a single request using the following endpoint:

POST /protected-areas/checks

With Registered Plot IDs

curl -X POST 'https://vantage.open-atlas.com/protected-areas/checks' \
-H "Authorization: Bearer $YOUR_BEARER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "plot_ids": [
    "8b9c3e0a-89e9-4dd3-9b2c-52b6f5b45c5e",
    "3fdbe0ae-99fc-4bd0-9ab1-b79347fce78e"
  ]
}'

Plots must be registered through the Vantage-X system using POST /plots/make_plot.

With Raw GeoJSON Geometries

curl -X POST 'https://vantage.open-atlas.com/protected-areas/checks' \
-H "Authorization: Bearer $YOUR_BEARER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "geojson": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [[[19.89, 0.36], [19.82, 0.32], [20.13, 0.20], [19.89, 0.36]]]
        }
      },
      {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [[[10.11, 20.22], [10.22, 20.33], [10.33, 20.11], [10.11, 20.22]]]
        }
      }
    ]
  }
}'

With Both

curl -X POST 'https://vantage.open-atlas.com/protected-areas/checks' \
-H "Authorization: Bearer $YOUR_BEARER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "plot_ids": [
    "8b9c3e0a-89e9-4dd3-9b2c-52b6f5b45c5e"
  ],
  "geojson": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [[[19.89, 0.36], [19.82, 0.32], [20.13, 0.20], [19.89, 0.36]]]
        }
      }
    ]
  }
}'

The response will be a single GeoJSON FeatureCollection, each feature containing the geometry and intersection analysis results:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-47.36821044, -13.95496867],
            [-47.36292406, -13.95496867],
            [-47.36292406, -13.95205871],
            [-47.36821044, -13.95205871],
            [-47.36821044, -13.95496867]
          ]
        ]
      },
      "properties": {
        "plot_id": "3fdbe0ae-99fc-4bd0-9ab1-b79347fce78e",
        "protected_areas": {
          "protected_area_overlap_summary": {
            "protected_area_overlap": true,
            "total_overlap_percentage": 100.0,
            "total_overlap_area_ha": 36.781606407618526,
            "most_restrictive_extractive_activity_legality": "prohibited"
          },
          "protected_area_details": [
            {
              "area_id": "20380",
              "area_name": "PARQUE NACIONAL DA CHAPADA DOS VEADEIROS",
              "local_name": "PARQUE NACIONAL DA CHAPADA DOS VEADEIROS",
              "source_name": "CNUC",
              "iucn_category": "Ib",
              "type": "Parque",
              "overlap_area_ha": 18.390803203809263,
              "extractive_activity_legality": "prohibited",
              "extractive_activity_conditions": null,
              "regulation_names": ["Law 9.985/2000 (SNUC)"],
              "regulation_urls": ["https://www.planalto.gov.br/ccivil_03/leis/l9985.htm"]
            },
            {
              "area_id": "20710",
              "area_name": "ÁREA DE PROTEÇÃO AMBIENTAL POUSO ALTO",
              "local_name": "ÁREA DE PROTEÇÃO AMBIENTAL POUSO ALTO",
              "source_name": "CNUC",
              "iucn_category": "IV",
              "type": "Área de Proteção Ambiental",
              "overlap_area_ha": 18.390803203809263,
              "extractive_activity_legality": "limited",
              "extractive_activity_conditions": "Agriculture, forestry, settlement, and industry are permitted.",
              "regulation_names": ["Law 9.985/2000 (SNUC)"],
              "regulation_urls": ["https://www.planalto.gov.br/ccivil_03/leis/l9985.htm"]
            }
          ],
          "sources": [
            {
              "source_name": "CNUC",
              "data_version": "2024-11-20"
            }
          ]
        }
      }
    }
  ]
}

Extractive Activity Restrictions

Every intersecting protected area now includes regulatory context describing whether extractive activities are permitted:

extractive_activity_legality reports if the site is prohibited, limited, permitted, or unknown.
extractive_activity_conditions explains the restrictions that apply whenever legality is limited.
regulation_names and regulation_urls cite the underlying decrees or statutes for audit purposes.
most_restrictive_extractive_activity_legality in protected_area_overlap_summary summarizes the strictest rule across all overlaps for that input geometry.
area_name, local_name, and type help distinguish how the protected area is labeled locally versus in canonical datasets.
source_name on each area (as well as the sources array with data_version) traces the authoritative dataset used for validation.

This information is validated against the authoritative regulation entries before being returned, so compliance teams can rely on the new attributes for defensible due diligence workflows.

Retrieve detailed information about an area

You can retrieve metadata for any protected area listed in a response using its area_id.

curl -X GET 'https://vantage.open-atlas.com/protected-areas/12345' \
-H "Authorization: Bearer $YOUR_BEARER_TOKEN"

This returns source information and classification metadata:

{
  "area_id": "12345",
  "name": "Bamboutos National Park",
  "country": "Cameroon",
  "iucn_category": "II",
  "protection_status": "Nationally Protected",
  "source": "",
  "local_name": "Parque Nacional Bamboutos",
  "type": "National Park"
}

Notes

The checks endpoint supports submitting both plot_ids and geojson in the same request.
The response includes one feature per input geometry or plot, preserving input order.
Plot IDs must come from the Vantage-X plot registration process using POST /plots/make_plot.
Currently, the protected area check result does not affect the risk level in Vantage-X. It is provided for transparency and due diligence purposes.

Authentication​

Run a Protected Area Check​

With Registered Plot IDs​

With Raw GeoJSON Geometries​

With Both​

Extractive Activity Restrictions​

Retrieve detailed information about an area​

Notes​