CSW API

Opendatasoft datasets can be accessed through a Catalog Service for the Web (CSW) API. CSW is a standard for exposing a catalog of geospatial records in XML.

The Opendatasoft platform uses the CSW specification version 2.0.2.

Operations supported

Opendatasoft platform implements four operations defined by the CSW standard:

Operation	Description
`GetCapabilities`	Retrieve service metadata
`DescribeRecord`	Discover elements of the information model by the catalog
`GetRecords`	Search for records and get their metadata and identifier
`GetRecordById`	Search for a record with a specific identifier

Service address and methods

Service entry address

GET https://documentation-resources.opendatasoft.com/api/csw 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 CSW API 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 CSW operations:

Operation	Description	Possible values	Optionality and use
`service`	The requested service	`CSW`	One (Mandatory)
`request`	The requested operation	`GetCapabilities`, `DescribeRecord`, `GetRecords`, `GetRecordById`	One (Mandatory)
`version`	The requested version of the service.	`2.0.2`	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:

be logged in a portal so a session cookie authenticating your user is passed along your API calls, or
provide an API key via the Authorization header or as a query parameter.

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.

Register their application with the Opendatasoft platform.
Request approval from users via an OAuth2 authorization grant.
Request a bearer token that will allows them to query the Opendatasoft platform APIs for a limited amount of time.
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

Go to the My applications tab of your account page on the domain you want to register the application on.
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
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:

Redirect them to /oauth2/authorize/ with the appropriate query parameters.
The user will then be authenticated in the platform and redirected to a page identifying your application.
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.
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:

client_id: the client ID you were given during registration
redirect_uri: the redirect URI you provided during registration
response_type: this should always be set to code
scopes (optional): a list of space-separated requested scopes. Currently only all is supported
state (optional): a random string of your choice

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:

code: a 30-characters-long authorization code
state: the state passed in the request described above

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:

client_id: the client ID you were given during registration
client_secret: the client secret you were given during registration
redirect_uri: the redirect URI you provided during registration
grant_type: this should always be set to authorization_code
code: the 30-character authorization code received as an authorization grant
scopes (optional): a list of space-separated requested scopes. Currently only all is supported
state (optional): a random string of your choice

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:

access_token: the token you can use to access the user's data.
expires_in: the number of seconds before token expiration
token_type: the type of the token. It will always be Bearer
state: the state passed in the request described above
scope: the list of scopes of this authorization code
refresh_token: a refresh token that can be used to renew this bearer token when expired

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:

as a query parameter of the request
in the request's Authorization header
in the request body

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:

client_id: the client ID you were given during registration
client_secret: the client secret you were given during registration
refresh_token: the refresh token returned in the bearer token response
grant_type: this should always be set to refresh_token
scopes: a list of space-separated requested scopes. Currently only all is supported
state (optional): a random string of your choice

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

Operations

GetCapabilities

Example GET request

GET https://documentation-resources.opendatasoft.com/api/csw?service=CSW&request=GetCapabilities&sections=ServiceIdentification,ServiceProvider HTTP/1.1

Example POST request

POST https://documentation-resources.opendatasoft.com/api/csw HTTP/1.1

<?xml version="1.0"?>
<GetCapabilities
  xmlns="http://www.opengis.net/cat/csw/2.0.2"
  xmlns:ows="http://www.opengis.net/ows"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.opengis.net/cat/csw/2.0.2/CSW-discovery.xsd"
  service="CSW">
  <ows:Sections>
      <ows:Section>ServiceIdentification</ows:Section>
      <ows:Section>ServiceProvider</ows:Section>
  </ows: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.

The existing parameters in the CSW 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	Contents
`ServiceIdentification`	Metadata about the CSW implementation.
`ServiceProvider`	Metadata about the organization offering the CSW service.
`OperationsMetadata`	Metadata about the CSW operations offered by a the CSW implementation.
`Filter_Capabilities`	Metadata about the filter capabilities of the server. The Opendatasoft CSW currently does not support filters.

GetRecords

GetRecords operation with the optional resultType, outputSchema and ElementSetName parameters

GET https://documentation-resources.opendatasoft.com/api/csw?service=CSW&request=GetRecords&resulttype=results&elementsetname=full&outputschema=http://www.isotc211.org/2005/gmd&typenames=csw:Record HTTP/1.1

Same request using a POST method

POST https://documentation-resources.opendatasoft.com/api/csw HTTP/1.1

<?xml version="1.0" ?>
<GetRecords
  service="CSW"
  resultType="results"
  outputSchema="http://www.isotc211.org/2005/gmd"
  xmlns="http://www.opengis.net/cat/csw/2.0.2"
  xmlns:ogc="http://www.opengis.net/ogc"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.opengis.net/cat/csw/2.0.2/CSW-discovery.xsd">
  <Query typeNames="Record">
      <ElementSetName>full</ElementSetName>
  </Query>
</GetRecords>

The GetRecords operation allows clients to discover resources (datasets). The response is an XML document and the output schema can be specified.

Parameters

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

The existing parameters in the CSW standard which are not listed in this table are currently not supported.

Parameter	Description	Optionality and use
`resultType`	Determines whether the catalog returns just a summary of the result set or includes one or more records from the result set.	Optional. Values can be `hits` or `results`. Default value is `hits`.
`outputSchema`	Used to indicate the schema of the output that is generated in response to a `GetRecords` request.	Optional. Values can be `http://www.opengis.net/cat/csw/2.0.2` or `http://www.isotc211.org/2005/gmd`. Default value is `http://www.opengis.net/cat/csw/2.0.2`.
`startPosition`	Used to indicate at which record position the catalog should start generating output.	Optional. Value must be a non-zero positive integer. Default value is 1.
`maxRecords`	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. Default value is 10.
`ElementSetName`	Used to indicate which named set the service shall present to the client. It usually defines the level of details present in the result set.	Optional. Values can be `full`, `summary`, or `brief`. Default value is `summary`.
`typeNames`	Used to indicate which named set the service shall present to the client. It usually defines the level of details present in the result set.	Mandatory. Values can be `csw:Record` or `gmd:MD_Metadata`.

DescribeRecord

DescribeRecord operation with the optional TypeName parameter

GET https://documentation-resources.opendatasoft.com/api/csw?service=CSW&request=DescribeRecord&typename=csw:Record HTTP/1.1

Same request using a POST method

POST https://documentation-resources.opendatasoft.com/api/csw HTTP/1.1

<?xml version="1.0" ?>
<DescribeRecord
    service="CSW"
    version="2.0.2"
    outputFormat="application/xml"
    schemaLanguage="http://www.w3.org/2001/XMLSchema"
    xmlns="http://www.opengis.net/cat/csw/2.0.2"
    xmlns:csw="http://www.opengis.net/cat/csw/2.0.2"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.opengis.net/cat/csw/2.0.2/CSW-discovery.xsd">
    <TypeName>csw:Record</TypeName>
</DescribeRecord>

The DescribeRecord operation allows clients to discover elements of the information model supported by the catalog service.

Parameters

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

The existing parameters in the CSW standard which are not listed in this table are currently not supported.

Parameter	Description	Optionality and use
`TypeName`	Unordered list of zero or more type names that are to be described by the catalog.	Optional. When omitted, return all types known.

GetRecordById

GetRecordById operation with the optional outputSchema parameter

GET https://documentation-resources.opendatasoft.com/api/csw?service=CSW&request=GetRecordById&outputschema=http://www.isotc211.org/2005/gmd&id=roman-emperors HTTP/1.1

Same request using a POST method

POST https://documentation-resources.opendatasoft.com/api/csw HTTP/1.1

<?xml version="1.0" ?>
  <GetRecordById
      service="CSW"
      version="2.0.2"
      outputFormat="application/xml"
      outputSchema="http://www.isotc211.org/2005/gmd"
      xmlns="http://www.opengis.net/cat/csw/2.0.2"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.opengis.net/cat/csw/2.0.2/csw/2.0.2/CSW-discovery.xsd">
      <Id>roman-emperors</Id>
  </GetRecordById>

The GetRecordById operation allows clients to retrieve the representation of catalog records using their identifier. The response is an XML document and the output schema can be specified.

Parameters

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

The existing parameters in the CSW standard which are not listed in this table are currently not supported.

Parameter	Description	Optionality and use
`outputSchema`	Used to indicate the schema of the output that is generated in response to a GetRecordById request.	Optional Values can be `http://www.opengis.net/cat/csw/2.0.2` or `http://www.isotc211.org/2005/gm` Default value is `http://www.opengis.net/cat/csw/2.0.2`
`ElementSetName`	Used to indicate which named set the service shall present to the client. It usually defines the level of details present in the result set.	Optional Values can be `full`, `summary` or `brief` Default value is `summary`
`Id`	A list of record identifiers for the records that a CSW shall return to the client.	Mandatory List of resource identifier