• WFS API
  • Authentication
  • Using OAuth2 authorization
  • Operations
  • WFS API

    Opendatasoft records can be accessed through a Web Feature Service (WFS), which provides an interface allowing requests for geographical features.

    The Opendatasoft platform uses the WFS specification version 1.1.0.

    Operations supported

    Opendatasoft platform implements three operations defined by the WFS standard:

    Operation Description
    GetCapabilities Retrieve service metadata
    DescribeFeatureType Generate a schema description of features types serviced by the service
    GetFeature Retrieve features from the service and output them using the GML representation

    Service address and methods

    Service entry address

    GET https://documentation-resources.opendatasoft.com/api/wfs HTTP/1.1
    

    The service can be reached at the following entry address.

    The domain https://documentation-resources.opendatasoft.com/ is used as an example in this documentation, but you should replace it with your custom domain name.

    The WFS supports both GET and POST HTTP methods.

    Request Headers

    The only supported HTTP header is the optional Content-Type header, which must be set to text/xml when using a POST HTTP request.

    Parameters

    When the HTTP GET method is used, the parameters are appended to the URL using a Keyword Value Pair (KVP) encoding.

    When the HTTP POST method is used, the operation request message is encoded as an XML document in the body of the POST message.

    Here is the list of the common parameters, supported by all WFS operations:

    Operation Description Possible values Optionality and use
    service The requested service WFS One (Mandatory)
    request The requested operation GetCapabilities, DescribeFeatureType, GetFeature One (Mandatory)
    version The requested version of the service 1.1.0 One (Optional)

    Exception reports

    Example exception

    <?xml version="1.0" encoding="UTF-8"?>
    <ExceptionReport xmlns="http://www.opengis.net/ows" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://schemas.opengis.net/ows/1.1.0/owsExceptionReport.xsd" version="1.0.0" language="en">
      <Exception exceptionCode="InvalidParameterValue" locator="service">
        <ExceptionText>Service must be WFS or CSW.</ExceptionText>
      </Exception>
    </ExceptionReport>
    

    When an error occurs, the service responds to the client using an Exception Report message to describe the error.

    Name Definition Data type and value Multiplicity and use
    ExceptionText Text describing specific exception represented by the exceptionCode Character String type, not empty. Value is an exception description as defined by individual servers Zero or more (optional). Omitted only when no more useful information available
    exceptionCode Code representing type of this exception Character String type, not empty. Allowed values are specified by each implementation specification and server
    implementation
    One (mandatory)
    locator Indicator of location in the client's operation request where this exception was encountered Character String type, not empty Contents defined for each allowed exceptionCode value for each operation Zero or one (optional). Omitted when no useful value available

    Authentication

    An authenticated user can be granted access to restricted datasets and benefit from extended quotas for API calls. The API features an authentication mechanism for users to be granted their specific authorizations.

    For the platform to authenticate a user, you need to either:

    Finding and generating API keys

    API keys are managed via your user profile page at https://<youropendatasoftportal>.com/account/ or by clicking on your name in the header.

    Link to account settings

    Go to the tab named My API keys to see your existing API keys, revoke them and create new ones.

    Account's API keys page

    Providing API keys within requests

    Unauthenticated request on a private portal

    > GET https://private-portal.opendatasoft.com/api/v2/catalog/datasets/ HTTP/1.1
    
    < HTTP/1.0 401 Unauthorized
    

    Authenticated request using an Authorization: Apikey <API_KEY> header

    > GET https://private-portal.opendatasoft.com/api/v2/catalog/datasets/ HTTP/1.1
    Authorization: Apikey 7511e8cc6d6dbe65f9bc8dae19e08c08a2cab96ef45a86112d303eee
    
    < HTTP/1.0 200 OK
    
    {
        "total_count": 4,
        "links": [{
            "href": "https://private-portal.opendatasoft.com/api/v2/catalog/datasets?include_app_metas=False&limit=10&offset=0",
            "rel": "self"
        }, {
            "href": "https://private-portal.opendatasoft.com/api/v2/catalog/datasets?include_app_metas=False&limit=10&offset=0",
            "rel": "first"
        }, {
            "href": "https://private-portal.opendatasoft.com/api/v2/catalog/datasets?include_app_metas=False&limit=10&offset=0",
            "rel": "last"
        }],
        "datasets": [...]
    }
    

    Authenticated request using an API key as a query parameter

    > GET https://private-portal.opendatasoft.com/api/v2/catalog/datasets/?apikey=7511e8cc6d6dbe65f9bc8dae19e08c08a2cab96ef45a86112d303eee HTTP/1.1
    
    < HTTP/1.0 200 OK
    
    {
        "total_count": 4,
        "links": [{
            "href": "https://private-portal.opendatasoft.com/api/v2/catalog/datasets?include_app_metas=False&limit=10&offset=0",
            "rel": "self"
        }, {
            "href": "https://private-portal.opendatasoft.com/api/v2/catalog/datasets?include_app_metas=False&limit=10&offset=0",
            "rel": "first"
        }, {
            "href": "https://private-portal.opendatasoft.com/api/v2/catalog/datasets?include_app_metas=False&limit=10&offset=0",
            "rel": "last"
        }],
        "datasets": [...]
    }
    

    If you try to access a private portal's catalog without being authenticated, the API returns a 401 Unauthorized error.

    After generating an API key, you can use it to make authenticated requests. Depending on the permissions granted to the user for which the API key has been created, the JSON response contains only data about the datasets this user can access on the portal.

    It is good practice to pass the API key to the Authorization header in the following format:

    Authorization: Apikey <API_KEY>

    Alternatively, you can pass the API key as a query parameter in the following format:

    apikey=<API_KEY>

    Replace <API_KEY>with your API key.

    Using OAuth2 authorization

    Overview

    Opendatasoft implements the OAuth2 authorization flow, allowing third party application makers to access the data hosted on an Opendatasoft platform on behalf of a user while never having to deal with a password, thus avoiding any user credential to be compromised.

    The Opendatasoft OAuth2 authorization flow is compliant with RFC 6749 and makes use of Bearer Tokens in compliance with RFC 6750.

    Application developers who want to use the Opendatasoft APIs with OAuth2 must go through the following steps, which will be explained in this section.

    1. Register their application with the Opendatasoft platform.
    2. Request approval from users via an OAuth2 authorization grant.
    3. Request a bearer token that will allows them to query the Opendatasoft platform APIs for a limited amount of time.
    4. Refresh the Bearer Token when it expires.

    Currently, applications are registered on a specific domain and can only access data on this domain.

    Register an application for OAuth2 authentication

    OAuth2 applications management interface

    1. Go to the My applications tab of your account page on the domain you want to register the application on.
    2. Fill the registration form with the following information:
      • Application name: the name of the application
      • Type:
        • confidential: client password is kept secret from the user and only used from a trusted environment (e.g: a web service, where the client password is stored server-side and never sent to the user)
        • public: client password is embedded in a client-side application, making it potentially available to the world (e.g: a mobile or desktop application)
      • Redirection URL: the URL users will be redirected to after they have granted you permission to access their data
    3. Store the resulting client ID and client secret that will be needed to perform the next steps.

    Getting an authorization grant

    Example call to /oauth2/authorize/

    GET /oauth2/authorize/?
        client_id=123456789&
        redirect_uri=https://example.com&
        response_type=code&
        state=ilovedata&
        scope=all HTTP/1.1
    

    To get an authorization grant from a user:

    1. Redirect them to /oauth2/authorize/ with the appropriate query parameters.
    2. The user will then be authenticated in the platform and redirected to a page identifying your application.
    3. From there, the user will review the information you filled in the form described above and the scope of the requested access, and grant your application the right to access their data.
    4. Once the user has accepted those terms, they will be redirected to your application's redirection URL with query parameters describing your authorization grant.

    The query parameters you need to supply when redirecting the user are the following:

    Redirection following a successful authorization

    HTTP/1.0 302 FOUND
    Location: https://example.com?state=ilovedata&code=gKnAQc2yIfdz2mY25xxgpTY2uyG5Sv
    

    The authorization grant redirect will have these values:

    The 30-character authorization code must now be converted into a bearer token within 1 hour before expiring.

    Converting an authorization grant to a bearer token

    Example call to /oauth2/token/

    POST /oauth2/token/ HTTP/1.1
    
    client_id=cid&
        client_secret=csc&
        grant_type=authorization_code&
        code=GokshWxRFXmW0MaLHkDv5HrG6wieGs&
        scopes=all&
        redirect_uri=https://example.com&
        state=ilovedata
    

    To receive a bearer token, convert the previously obtained authorization grant via a POST request to /oauth2/token/ with the following parameters:

    Alternative call with an Authorization header

    POST /oauth2/token/ HTTP/1.1
    Authorization: Basic Y2lkOmNzYw==
    
    grant_type=authorization_code&
        code=GokshWxRFXmW0MaLHkDv5HrG6wieGs&
        scopes=all&
        redirect_uri=https://example.com&state=ilovedata
    

    Alternatively, you can pass your client ID and client secret through the Authorization header

    Example response for a bearer token request

    HTTP/1.0 200 OK
    Content-Type: application/json
    
    {
        "access_token": "9kxoTUYvSxnAiMpv008NBqRiqk5xWt",
        "expires_in": 3600,
        "token_type": "Bearer",
        "state": "ilovedata",
        "scope": "all",
        "refresh_token": "jFfDUcsK9zzNMs1zwczzJxGrimPtmf"
    }
    

    The response to this request is a JSON representation of a bearer token, which contains the following values:

    Using the bearer token

    Using the token as a query parameter

    GET /api/end/point?access_token=9kxoTUYvSxnAiMpv008NBqRiqk5xWt HTTP/1.1
    

    Using the token in an Authorization header

    GET /api/end/point HTTP/1.1
    Authorization: Bearer 9kxoTUYvSxnAiMpv008NBqRiqk5xWt
    

    Using the token in the request body

    GET /api/end/point HTTP/1.1
    
    access_token=9kxoTUYvSxnAiMpv008NBqRiqk5xWt
    

    The bearer token can be passed along requests for authentication in three different ways:

    Refreshing a bearer token

    Example token refresh call

    POST /oauth2/token/ HTTP/1.1
    
    client_id=cid&
        client_secret=csc&
        grant_type=refresh_token&
        refresh_token=jFfDUcsK9zzNMs1zwczzJxGrimPtmf&
        scopes=all&
        redirect_uri=https://example.com&
        state=ilovedata
    

    To refresh an expired bearer token, send a request to the /oauth2/token/ endpoint, with the following query parameters:

    The response to this request is identical to the bearer token response.

    Operations

    GetCapabilities

    GetCapabilities operation with the optional Sections parameter

    GET https://documentation-resources.opendatasoft.com/api/wfs?service=WFS&request=GetCapabilities&sections=OperationsMetadata,FeatureTypeList HTTP/1.1
    

    Same request using a POST method

    POST https://documentation-resources.opendatasoft.com/api/wfs HTTP/1.1
    
    <?xml version="1.0" encoding="UTF-8"?>
    <GetCapabilities xmlns="http://www.opengis.net/ows"
      xmlns:ows="http://www.opengis.net/ows"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.opengis.net/ows
      fragmentGetCapabilitiesRequest.xsd"
      service="WFS">
      <Sections>
          <Section>OperationsMetadata</Section>
          <Section>FeatureTypeList</Section>
      </Sections>
    </GetCapabilities>
    

    The GetCapabilities operation allows clients to retrieve service metadata. The response is an XML document containing the information.

    Parameters

    This is the list of the supported parameters specific to the GetCapabilities operation. You should also take into consideration the common parameters. See more.

    The existing parameters in the WFS standard that are not listed in this table are currently not supported.

    Parameter Description Optionality and use
    Sections Unordered list of zero or more names of sections of service metadata document to be returned in service metadata
    document.
    Optional. When omitted, returns the complete service metadata document.
    AcceptVersions Prioritized sequence of one or more specification versions accepted by client, with preferred versions listed
    first.
    Optional. When omitted, returns the latest supported version.

    Sections

    This is the list of the existing section in the service metadata. The section name can be used as a value for the Sections parameter.

    Section name Content
    ServiceIdentification Metadata about the WFS implementation
    ServiceProvider Metadata about the organization offering the WFS service
    OperationsMetadata Metadata about the WFS operations offered by the WFS implementation
    FeatureTypeList List of features types that are available from the service

    DescribeFeatureType

    DescribeFeatureType operation with the optional TypeName parameter

    GET https://documentation-resources.opendatasoft.com/api/wfs?service=WFS&request=DescribeFeatureType&typeName=ods:roman-emperors HTTP/1.1
    

    Same request using a POST method

    POST documentation-resources.opendatasoft/api/wfs HTTP/1.1
    
    <?xml version="1.0" ?>
    <DescribeFeatureType
        version="1.1.0"
        service="WFS"
        xmlns="http://www.opengis.net/wfs"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.opengis.net/wfs ../wfs/1.1.0/WFS.xsd">
        <TypeName>ods:roman-emperors</TypeName>
    </DescribeFeatureType>
    

    The DescribeFeatureType operation generates a schema description of features types serviced by the WFS.

    Parameters

    This is the list of the supported parameters specific to the DescribeFeatureType operation. You should also take into consideration the common parameters. See more

    The existing parameters in the WFS standard that are not listed in this table are currently not supported.

    Parameter Description Optionality and use
    TypeName A comma-separated list of feature types to describe. Optional. When omitted, return all feature types known.

    GetFeature

    GetFeature operation with the optional PropertyName parameter

    GET https://documentation-resources.opendatasoft.com/api/wfs?service=WFS&request=GetFeature&typename=ods:roman-emperors&propertyname=ods:roman-emperors/name HTTP/1.1
    

    Same request using a POST method

    POST https://documentation-resources.opendatasoft.com/api/wfs HTTP/1.1
    
    <?xml version="1.0" encoding="UTF-8"?>
    <wfs:GetFeature
      service="WFS"
      version="1.1.0"
      xmlns:wfs="http://www.opengis.net/wfs"
      xmlns:ogc="http://www.opengis.net/ogc"
      xmlns:myns="http://www.someserver.com/myns"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.opengis.net/wfs ../wfs/1.1.0/WFS.xsd">
      <wfs:Query typeName="ods:roman-emperors">
          <wfs:PropertyName>name</wfs:PropertyName>
      </wfs:Query>
    </wfs:GetFeature>
    

    The GetFeature operation allows retrieval of features from the WFS, and output them using the GML 3.1.1 representation.

    Parameters

    This is the list of the supported parameters specific to the GetFeature operation. You should also take into consideration the common parameters. See more.

    The existing parameters in the WFS standard that are not listed in this table are currently not supported.

    Parameter Description Optionality and use
    resultType Used to indicate whether a WFS should generate a complete response document or an
    empty response document indicating only the number of features that the query would return
    Optional. Values can be hits or results. Default value is results
    maxFeatures Used to define the maximum number of records that should be returned from the result set of a query Optional. Value must be a positive integer
    TypeName A list of feature type names to query Mandatory
    PropertyName A list of properties that should be returned Optional. The absence of a value also indicates that all properties should be fetched
    featureId An enumerated list of feature instances to fetch identified by their feature identifiers Optional