Language
Basemap access
If you do not already have a OneAtlas account, please register here.
You will receive login credentials for your account. This account allows you to manage your accesses to the Basemap as described in Basemap access section. The OneAtlas account is your main account which can be used to access several One Atlas services. To be authorized to access the Basemap streaming service, you need to contact our Sales department or Customer Care support.
Authenticate
Every request sent to the Basemap server needs to be authenticated. It means that some credentials are sent with the request allowing the server to verify user identity and authorizations.
The Basemap can be accessed through one of the 2 authentication methods described in the following section:
- Basic authentication: Use of basic authentication is based on API Key and is usually limited to GIS tools as credentials can easily be hacked.
- Bearer token authentication: Use of Bearer token authentication is more secure than basic authentication.
Basic authentication
Basic authentication means that the username and password are sent into the HTTP header of the request. The username and password are encrypted in base64.
Request
| API Endpoint | <Basemap Endpoint> |
| REST verb | GET |
| Authorization | Basic <base64 username:password> |
cURL example: The following cURL example sends a GET HTTP request to the ‘https://view-bm.api.oneatlas.airbus.com/basemap/wmts?SERVICE=WMTS&REQUEST=GetCapabilities’ Basemap endpoint, passing base64 username:password value as basic authentication:
> curl --request GET 'https://view-bm.api.oneatlas.airbus.com/basemap/wmts?SERVICE=WMTS&REQUEST=GetCapabilities' --header 'Authorization: Basic <base64 username:password>'
base64 value can be generated with the following command:
> echo "$(echo -n 'username:password' | base64)" | tr -d '\n'
> dXNlcm5hbWU6cGFzc3dvcmQ=
base64 value of ‘username:password’ is dXNlcm5hbWU6cGFzc3dvcmQ=
Note that cURL provides the –user option to avoid base64 transformation:
> curl --request GET 'https://view-bm.api.oneatlas.airbus.com/basemap/wmts?SERVICE=WMTS&REQUEST=GetCapabilities' --user username:password
The basic authentication for Basemap streaming uses the One Atlas API Key which is your digital signature identifying you as a user of OneAtlas services. The username and password to access the Basemap service are defined as follow:
| Username | APIKEY |
| Password | <API Key Value> |
The username is always “APIKEY” in capital letter, while the password is the API Key value. The following section describes the way to retrieve your API Key value(s)
Get your API Key
To get your One Atlas API Key, go to the API Key Generator page. Log in with your One Atlas account credentials created at Request access to Basemap section. Click on “Create an API Key”:
A new API Key window pops-up: 
Save the API Key value in a safe location as there is no copy of it. If this API Key is lost, another API Key needs to be created again from scratch.
Note: Please ensure you protect your API Key. If anyone else gains access to it, they will be able to make requests and use your balance.
A user can generate up to 10 API Keys. This could be convenient if you need to access to the One Atlas services in different context, for example from different tools or validity periods.
Usage example: The following cURL example sends a GET HTTP request to the ‘https://view-bm.api.oneatlas.airbus.com/basemap/wmts?SERVICE=WMTS&REQUEST=GetCapabilities’ basemap endpoint, passing the API Key value:
> curl --request GET 'https://view-bm.api.oneatlas.airbus.com/basemap/wmts?SERVICE=WMTS&REQUEST=GetCapabilities' --user APIKEY:<API Key value>
Note: An API Key is defined with an expiration date at creation. It is important to manage this constraint and to anticipate rotations. A good practice is to define regular rotations of API Keys. If your API Key expires, you won’t be able to use any service.
Bearer token authentication
Bearer token authentication means that a token is sent into the HTTP header of the request. A token contains information about user identity and authorizations:
Request
| API Endpoint | <Basemap Endpoint> |
| REST verb | GET |
| Authorization | Bearer <Access token> |
cURL example: The following cURL example sends a GET HTTP request to the ‘https://view-bm.api.oneatlas.airbus.com/basemap/wmts?SERVICE=WMTS&REQUEST=GetCapabilities’ Basemap endpoint, passing <Access Token> in bearer token authentication:
> curl --request GET 'https://view-bm.api.oneatlas.airbus.com/basemap/wmts?SERVICE=WMTS&REQUEST=GetCapabilities' --header 'Authorization: Bearer <Access Token>'
The following section describes the way to retrieve your Access Token value(s)
Get your Access Token
An API Key is your digital signature identifying you as a user of OneAtlas services. Using this key created in the ‘Get your API Key’ section, you can get an access token.
Note: For security reasons, access tokens expire regularly, then it’s necessary to get a new one. Tokens lifetime is defined by Airbus Authentication Service. Currently, tokens lifetime is set to one hour. It is recommended to:
- Implement an access token cache in your application
- Avoid huge volume of Authentication API requests
- Anticipate new access token requests before the expiration limit
The endpoint to use to generate access tokens is described in the following table:
Request
| Endpoint | https://authenticate.foundation.api.oneatlas.airbus.com/auth/realms/IDP/protocol/openid-connect/token |
| REST verb | POST |
The required parameters are listed in the table below:
| Parameters | Required | Description |
|---|---|---|
| apikey | yes | The OneAtlas API Key. See ‘Get your API Key’ section |
| client_id | yes | Should be ‘IDP’ value for Basemap service |
| grant_type | yes | Should be ‘api_key’ value for API authentication. |
Below is an example to retrieve an access token with the API Key:
> curl -X POST https://authenticate.foundation.api.oneatlas.airbus.com/auth/realms/IDP/protocol/openid-connect/token -d 'apikey=<API Key>&grant_type=api_key&client_id=IDP'
If the authentication information is valid, then the return JSON structured provides an access token and its validity duration.
{
"access_token": "<access_token>",
"expires_in": 3600,
"token_type": "Bearer"
}
However, if authentication information is invalid or omitted, an error message will be returned with status code 403:
{
"error": "access_denied",
"error_description": "Access denied"
}
Note: For security reason, providing an incorrect API key will automatically suspend the authorization to access the API for a limited period of time. During this suspension period, the user will receive a 403 error, even if the API key is valid.
Streaming from API
This section details how to use the WMTS protocol to stream the Basemap. The Basemap server exposes the Basemap endpoint https://view-bm.api.oneatlas.airbus.com/basemap/wmts with 2 request types defined by the standard and described in the following sections:
- GetCapabilities
- GetTile
If you are not familiar with WMTS protocols, you can read the ‘WMTS basics’ section.
GetCapabilities API
To retrieve the Basemap WMTS information, user authorized layer(s) and the tiling scheme used for Basemap streaming, you should use the GetCapabilities request. The characteristics of the endpoint to access to the GetCapabilities are:
Request
| API Endpoint | https://view-bm.api.oneatlas.airbus.com/basemap/wmts?SERVICE=WMTS&REQUEST=GetCapabilities |
| REST verb | GET |
| Authorization | Basic or Bearer token (see Authenticate section) |
cURL examples:
The following cURL example sends a GetCapabilities request to the ‘https://view-bm.api.oneatlas.airbus.com/basemap/wmts’ Basemap endpoint, passing <username:password> value as basic authentication:
> curl --request GET 'https://view-bm.api.oneatlas.airbus.com/basemap/wmts?SERVICE=WMTS&REQUEST=GetCapabilities' --user APIKEY:<API Key value>
See Authenticate section for <API Key value> retrieval
The following cURL example sends a GetCapabilities request to the ‘https://view-bm.api.oneatlas.airbus.com/basemap/wmts’ basemap endpoint, passing <Access Token> in bearer token authentication:
> curl --request GET 'https://view-bm.api.oneatlas.airbus.com/basemap/wmts?SERVICE=WMTS&REQUEST=GetCapabilities' --header 'Authorization: Bearer <Access Token>'
See Authenticate section for <Access Token> retrieval
As an answer, it returns an XML file with tiles. Below is an extract of the answer:
Note: The <Layer> tag returns the streaming layer authorized for the user. There can be several layer per user. The <Layer>/<Identifier> tag returns the name of the layer to be used to retrieve the Basemap tiles.
GetTile API
To retrieve a Basemap tile, you should use the GetTile request. The characteristics of the endpoint to access to the GetTile are:
Request
| API Endpoint | https://view-bm.api.oneatlas.airbus.com/basemap/wmts?style=default&tilematrixset=3857&Service=WMTS&Request=GetTile&Version=1.0.0&Format=image/unknown&layer=<BasemapLayerName>&TileMatrix=<WmtsZoomLevel>&TileCol=<WmtsAbscissa>&TileRow=<WmtsOrdinates> |
| REST verb | GET |
| Authorization | Basic or Bearer token (see Authenticate section) |
<BasemapLayerName> is the layer you want to get a tile from. <WmtsZoomLevel>/<WmtsAbscissa>/<WmtsOrdinates> is the triplet identifying the tile to be retrieved
cURL examples:
The following cURL example sends a GetTile request to the ‘https://view-bm.api.oneatlas.airbus.com/basemap/wmts’ basemap endpoint, passing <username:password> value as basic authentication:
> curl --request GET 'https://view-bm.api.oneatlas.airbus.com/basemap/wmts?style=default&tilematrixset=3857&Service=WMTS&Request=GetTile&Version=1.0.0&Format=image/unknown&layer=advancedBasemap&TileMatrix=19&TileCol=264129&TileRow=191412' --user APIKEY:<API Key value>
See Authenticate section for <API Key value> retrieval
The following cURL example sends a GetTile request to the ‘https://view-bm.api.oneatlas.airbus.com/basemap/wmts’ basemap endpoint, passing <Access Token> in bearer token authentication:
> curl --request GET 'https://view-bm.api.oneatlas.airbus.com/basemap/wmts?style=default&tilematrixset=3857&Service=WMTS&Request=GetTile&Version=1.0.0&Format=image/unknown&layer=advancedBasemap&TileMatrix=19&TileCol=264129&TileRow=191412' --header 'Authorization: Bearer <Access Token>'
See Authenticate section for <Access Token> retrieval The request answer is the Zoom level 19 tile located in X=264129 Y=191412:
Streaming from GIS tools
Geographic Information System (GIS) applications are a common (and one of the simplest) way to display the Basemap as they act as a WMTS client. To display the Basemap in GIS applications, please refer to the GIS tool user guide and follow instructions to add a WMTS server. The Basemap server URL to configure is the GetCapabilities endpoint:
| GIS URL Endpoint | https://view-bm.api.oneatlas.airbus.com/basemap/wmts?SERVICE=WMTS&REQUEST=GetCapabilities |
The Basemap server is not public so you have to authenticate in the GIS application. Usually, GIS tools are only compatible with basic authentication, meaning that you should provide username and password (see ‘Basic authentication’ section) when adding the Basemap server. QGIS and ArcMap/ArcGIS being two of the most used GIS applications, you can find details on displaying the Basemap on these 2 application in the following sections.
Basemap in QGIS
This section details the way to display the Basemap in QGIS application. Please note that QGIS is a free and open source GIS fully managed by the QGIS community. In this section, you can find the procedure to display the Basemap in QGIS 3.24.3-Tisler version running on Linux Fedora 36 which should be very similar to all QGIS version running on any Operating System. Nevertheless, for any QGIS question, please refer to the QGIS community: https://qgis.org
In the QGIS menu, select ‘Layer/Add Layer/Add WMS/WMTS Layer…’ to open the ‘Data Source Manager | WMS/WMTS’ window:
Click a ‘New’ to open the ‘Create a New WMS/WMTS Connection’ window:
Fill in the ‘Create a New WMS/WMTS Connection’ window as follow:
Name: Choose a name for your connection URL: The GIS URL endpoint provided in the ‘Streaming from GIS tools’ User Name: APIKEY Password: Your API Key value (see ‘Basic authentication’ section)
Click OK and Close. You should see your connection name in the Browser panel:
Expand the connection to show the layers available for the user:
In this example, the user can access three layers: advancedBasemap, italyBasemap and ukraineBasemap. Double click on the layer you want to display to start streaming:
Zoom in and out wherever you want if you are authorized to stream worldwide. If you stream is geofenced, zoom in and out in the areas you are authorized to:
Basemap in ArcMap/ArcGIS
This section details the way to display the basemap in ArcMap/ArcGIS application. Please note that ArcMap/ArcGIS is distributed by ESRI. In this section, you can find the procedure to display the basemap in ArcMap/ArcGIS version 10.5.1.7333 version running on Windows 10 Entreprise 20H2 which should be very similar to all ArcMap/ArcGIS version running on any Operating System. Nevertheless, for any ArcMap/ArcGIS question, please refer to ESRI: https://www.esri.com/en-us/arcgis/products/arcgis-desktop/overview
In ArcMap, double click ‘GIS servers/Add WMTS server’ in the catalog window: 
Fill in the ‘Add WMTS server’ window as follow:
URL: The GIS URL endpoint provided in the ‘Streaming from GIS tools’ User: APIKEY Password: Your API Key value (see ‘Basic authentication’ section)
Click OK, a new connection “One Atlas Basemap Streamer on view-bm.api.oneatlas.airbus.com” should appear in the catalog window:
Double click the new connection and expand it:
In this example, the user can access three layers: advancedBasemap, italyBasemap and ukraineBasemap.
Drag and drop the layer name you want to display into the main window to start streaming:
Zoom in and out wherever you want if you are authorized to stream worldwide. If you stream is geofenced, zoom in and out in the areas you are authorized to:
ArcGis portal integration
Specific configuration is necessary in ArcGis portal to access the Basemap.
Add url https://view-bm.api.oneatlas.airbus.com in ArcGis Portal « Trusted Servers » Organization / Settings / Security / Trusted Servers: Do not forget to Save - button at the bottom of the page.
Then it’s possible to add the Basemap layer : https://view-bm.api.oneatlas.airbus.com/basemap/wmts?SERVICE=WMTS&REQUEST=GetCapabilities) as an Item or directly in a WebMap.
This will open an authentication window. You will be allowed to enter your credentials:
Web application integration
If you plan to distribute the Basemap content through a web Application, you should make the API Key ot Access token visible from the Web Application. Instead, you should rely on a proxy backend. This backend has to be deployed in Web Application provider infrastructure; being responsible for the storage of the API Key. Please remind that you are responsible to protect your API Key. If anyone else gains access to it, they will be able to make requests and use your balance. The architecture is depicted below:
WMTS basics
This section aims at describing the basics of the Web Map Tile Service (WMTS) standard to ease the understanding of Basemap streaming. For a detailed description of the WMTS standard, please refer to the Open Geospatial Consortium (OGC) https://www.ogc.org/standards/wmts. The WMTS standard provides an efficient way to display worldwide maps through a network called streaming. Instead of requesting the full image, the client requests, for each zoom level, a set of tiles to display its Basemap area of interest. At each zoom level, the Basemap is divided in a number of tiles starting from zoom level 0 up to zoom level 19 for the Basemap. As the zoom level increases, the number of tiles dividing the Basemap increases in a way that the resolution of a tile increases with the zoom level:
The WMTS standard defines that every tile, at each zoom level, is 256 pixels by 256 pixels. In the epsg:3857 projection, the first level of zoom is composed of a single tile representing the whole world. The next level represents the whole world in 4 tiles (2x2) and so on in powers of 4. The WMTS tiling scheme in epsg:3857 projection is consequently:
| Zoom level | Pixel size | Nb tiles on abscissa | Nb tiles on ordinate |
|---|---|---|---|
| 0 | 156543,0339 | 1 | 1 |
| 1 | 78271,5170 | 2 | 2 |
| 2 | 39135,7585 | 4 | 4 |
| 3 | 19567,8792 | 8 | 8 |
| 4 | 9783,9396 | 16 | 16 |
| 5 | 4891,9698 | 32 | 32 |
| 6 | 2445,9849 | 64 | 64 |
| 7 | 1222,9925 | 128 | 128 |
| 8 | 611,4962 | 256 | 256 |
| 9 | 305,7481 | 512 | 512 |
| 10 | 152,8741 | 1024 | 1024 |
| 11 | 76,4370 | 2048 | 2048 |
| 12 | 38,2185 | 4096 | 4096 |
| 13 | 19,1093 | 8192 | 8192 |
| 14 | 9,5546 | 16384 | 16384 |
| 15 | 4,7773 | 32768 | 32768 |
| 16 | 2,3887 | 65536 | 65536 |
| 17 | 1,1943 | 131072 | 131072 |
| 18 | 0,5972 | 262144 | 262144 |
| 19 | 0.2986 | 524288 | 524288 |
The WMTS standard also defines the way to uniquely identify a tile. At a given zoom level, abscises and ordinates are numbered from 0 to (Nb tiles - 1). Starting from top left corner, abscises increment towards the east, while ordinates increment towards the south.
The WMTS standard defines a GetTile request API which is a HTTP request for a unique tile. When requesting a tile from GetTile API, the client requests a tile providing its zoom level and coordinates: TileMatrix=zoom level, TileCol=abscises and TileRow=ordinates. When a client wants to display a map on a screen, it requests the tiles needed to fill the screen. For example, if the screen is 1024 pixels by 1024 pixels, it requests 16 tiles of 256 pixels by 256 pixels each.
The WMTS standard also comes with a ‘layer’ mechanism allowing to stream different contents from the same server. ‘Layer’ mechanism is implemented by the Basemap server, meaning that you could stream 2 different basemaps with 2 different contents from the Basemap server. The 2 layers information are provided by a GetCapibilities request answer. You specify the layer in the GetTile request to get a tile from one layer or the other.
© Airbus Defence and Space 2022. All rights reserved. Privacy Policy | Legal Information