Introduction
============

The Planviewer Product API enables developers to order and download products for third party
applications.

This documentation consists of two main sections. First, the
:doc:`Product API Dashboard <dashboard>` section gives an intruction into the
dashboard profile pages for the Product API. This is where you need to start by
configuring an application and allows a reseller to track the API usage.

The second section concerns using the server-side API. These
server calls allow your application to retrieve data, order products and
finally to download the results.

Workflow
--------

1. In the Planviewer API dashboard an *Application* should be created by
   the *Reseller* of the *Customer*.
2. For the *Application* an *Access Key* can be generated for Server-to-Server Product API communication.
3. The *Customer* finds out which :doc:`products` are interesting and remembers the relevant slugs.
4. The *Implementation* of the *Customer* can :doc:`search <search>` for *Locations*.
5. For a *Location* and a desired *Product* a set of :doc:`Product Intentions <intentions>` is yielded. The *Implementation* selects a *Product Intention* to order.
6. A :doc:`Job <jobs>` is created, and the *Implementation* waits until the *Job* is finished.
7. The *Implementation* downloads the result of the *Job*.

Server calls
------------

The Product API is exclusively comprised of Server-to-Server communication, where calls are made by the Customers
server to `planviewer.nl <https://www.planviewer.nl>`_. Authentication of this communication is provided by Planviewer API access keys.
For all requests in this section the user and password must be provided as HTTP basic auth parameters.
For more information on this read
the general :doc:`Authentication Access Keys <../api/accesskeys>` section.

.. _productapi-glossary:

Glossary
--------

.. glossary::
    Application
        An application is used to allow access from your platform to the
        planviewer data. You can maintain a different set of security
        credentials, a different set of map layers and a different set of maps
        per application.

    Reseller
        The party that interacts with Planviewer on a business-level.
        The user account of the reseller is used to configure all aspects of the Product API.

    Customer
        The party that interacts with the reseller, and uses an *Implementation* to interact with Planviewer services.

    Implementation
        A system that implements the Planviewer Product API, and thus consumes products.

    API Access Key
        An API Acccess Key allows a server to use the server API methods
        provided by the Product API. The API Access Key is acting as a username
        for your server, whereas the Access Key Secret is used as a password
        and should never be known publicly.

    Access Key Secret
        See *API Access Key*.

    Location
        The subject of any product. All Planviewer products concern a specific location within the Netherlands.
        Conceptually a location can be either an address or a lot, as far as the Product API is concerned.

    Product
        The concept of a marketable file that can be ordered. Given a concrete location, a product can yield multiple PDF documents, shapes files or other files.

    Product intention
        A concrete intention of a product that can be ordered. For example, given a location, several bestemmingsplannen may be available.
        A product intention in this case is a single report for a specific bestemmingsplan and a specific location, that can be ordered.

    Job
        The asynchronous process which generates a file from a product intention. A job can finish, or fail.
        Files that result from finished jobs can be downloaded.