Language
OneAtlas Basemap Guide
  1. Using Your Own Code
    1. Using WMS Protocol
    2. Using WMTS Protocol
      1. GetCapabilities
      2. Get Tiles for a Geographic Tile Matrix Set
      3. Get Tiles for a Web Mercator Tile Matrix Set

Using Your Own Code

As an example, we will use the following area of San Francisco International Airport:

SanFranciscoAirport_map.png

The coordinates of the bounding box are:

LongitudeLatitude
Upper left corner-122,38594651222237,6203332456312
Bottom right corner-122,38220214843737,6176733171484

Using WMS Protocol

OneAtlas Basemap follows the OGC standard defining the WMS protocol: https://www.opengeospatial.org/standards/wms.


Using the WMS endpoint, the GetCapabilities service request is invoked to retrieve the WMS streaming endpoint:

curl -X GET -H "Authorization: Bearer <API_KEY>" "https://view.geoapi-airbusds.com/api/v1/map/imagery.wms?version=1.1.1&request=GetCapabilities&service=WMS"

The response should look like:

<?xml version='1.0' encoding="UTF-8" standalone="no" ?>
<!DOCTYPE WMT_MS_Capabilities SYSTEM "http://schemas.opengis.net/wms/1.1.1/WMS_MS_Capabilities.dtd" [

<!ELEMENT VendorSpecificCapabilities EMPTY>
]>
<WMT_MS_Capabilities version="1.1.1" updateSequence="0">
    <Service>
        <Name>cf11e122-4f20-11e6-b6b4-3fb4985d5498</Name>
        <Title>OneAtlas Internal Team Worldwide</Title>
        <Abstract>One Atlas - The world's freshest basemap at your fingertips</Abstract>
        <OnlineResource xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://view.geoapi-airbusds.com/mugg/wms/cf11e122-4f20-11e6-b6b4-3fb4985d5498?"/>
        <ContactInformation>
            <ContactPersonPrimary>
                <ContactPerson>One Atlas Support</ContactPerson>
                <ContactOrganization>Airbus DS Intelligence</ContactOrganization>
            </ContactPersonPrimary>
            <ContactPosition>One Atlas Support</ContactPosition>
            <ContactAddress>
                <AddressType>mailing and physical</AddressType>
                <Address>5, rue des Satellites</Address>
                <City>Toulouse</City>
                <StateOrProvince>-</StateOrProvince>
                <PostCode>31030</PostCode>
                <Country>France</Country>
            </ContactAddress>
            <ContactVoiceTelephone>-</ContactVoiceTelephone>
            <ContactFacsimileTelephone>-</ContactFacsimileTelephone>
            <ContactElectronicMailAddress>oneatlas_helpdesk_gccc@airbus.com</ContactElectronicMailAddress>
        </ContactInformation>
    </Service>
    <Capability>
        <Request>
            <GetCapabilities>
                <Format>application/vnd.ogc.wms_xml</Format>
                <DCPType>
                    <HTTP>
                        <Get>
                            <OnlineResource xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://view.geoapi-airbusds.com/mugg/wms/cf11e122-4f20-11e6-b6b4-3fb4985d5498?"/>
                        </Get>
                    </HTTP>
                </DCPType>
            </GetCapabilities>
            <GetMap>
                <Format>image/jpeg</Format>
                <Format>image/png</Format>
                <DCPType>
                    <HTTP>
                        <Get>
                            <OnlineResource xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://view.geoapi-airbusds.com/mugg/wms/cf11e122-4f20-11e6-b6b4-3fb4985d5498?"/>
                        </Get>
                    </HTTP>
                </DCPType>
            </GetMap>
        </Request>
        <Exception>
            <Format>application/vnd.ogc.se_xml</Format>
        </Exception>
        <Layer>
            <Title>OneAtlas Internal Team Worldwide</Title>
            <Abstract>One Atlas - The world's freshest basemap at your fingertips</Abstract>
            <SRS>EPSG:3857</SRS>
            <SRS>EPSG:4326</SRS>
            <LatLonBoundingBox minx="-180" miny="-85.05113" maxx="180" maxy="85.05113" />
            <Layer queryable="0" opaque="0" cascaded="0">
                <Name>0</Name>
                <Title>OneLive</Title>
                <Abstract>Top quality, never ageing basemap.</Abstract>
                <LatLonBoundingBox minx="-180" miny="-85.05113" maxx="180" maxy="85.05113" />
            </Layer>
        </Layer>
    </Capability>
</WMT_MS_Capabilities>

The WMS streaming endpoint can be found under the /Capability/request/GetMap/DCPType/HTTP/Get path. In our example, the endpoint is https://view.geoapi-airbusds.com/mugg/wms/cf11e122-4f20-11e6-b6b4-3fb4985d5498?.

<WMT_MS_Capabilities version="1.1.1" updateSequence="0">
    ...
    <Capability>
        <Request>
            ...
            <GetMap>
                ...
                <DCPType>
                    <HTTP>
                        <Get>
                            <OnlineResource xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://view.geoapi-airbusds.com/mugg/wms/cf11e122-4f20-11e6-b6b4-3fb4985d5498?"/>
                        </Get>
                    </HTTP>
                </DCPType>
            </GetMap>
        </Request>
        ...
    </Capability>
</WMT_MS_Capabilities>

Afterwards, you can use the WMS protocol to access the image of the bounding box. In this example we show a number of parameters needed to make a successful GetMap request:

curl -X GET -H "Authorization: Bearer <API_KEY>" "https://view.geoapi-airbusds.com/mugg/wms/cf11e122-4f20-11e6-b6b4-3fb4985d5498?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&BBOX=-122.385946512222,37.6176733171484,-122.382202148437,37.6203332456312&SRS=EPSG:4326&WIDTH=600&HEIGHT=400&LAYERS=0&STYLES=&FORMAT=image/png"
API endpointWMS endpoint (see Manage Subscriptions)
VERSION=1.1.1This is the WMS version supported by the basemap
REQUEST=GetMapThis is the request name.
SRSThis is the spatial reference value. The value could be EPSG:4326 or EPSG:3857
BBOXThis is the ounding box for map extent. The value is 'minX, minY, maxX, maxY' in units of the SRS.
WIDTH / HEIGHTThis is the width or height of the requested image in pixels.
FORMAT=image/pngThis is the requested image format.

Here we can see the PNG result of the request above for the requested pixel size (600 × 400) satisfying our bounding box:

WMSsanFrancisco.png

Using WMTS Protocol

This section details how to use the WMTS protocol from your own code. To do so, you will need to convert geographic coordinates into tiles coordinates.

GetCapabilities

To retrieve the basemap WMTS information and the tiles detailed schema used, you should use the GetCapabilities service:


The characteristics of the endpoint to access to the GetCapabilities are:

API EndpointWMS endpoint (see Manage Subscriptions)
REST verbGET
AuthenticationBearer access token

Here is an example of a GetCapabilities request:

curl -X GET -H "Authorization: Bearer <API_KEY>" "https://view.geoapi-airbusds.com/api/v1/map/imagery.wmts?request=GetCapabilities"

This will return an XML file with tiles. Below you can see an extract the XML file:

<TileMatrix>
  <ows:Identifier>12</ows:Identifier>
  <ScaleDenominator>68247.34668319309</ScaleDenominator>
  <TopLeftCorner>90.000000 -180.000000</TopLeftCorner>
  <TileWidth>256</TileWidth>
  <TileHeight>256</TileHeight>
  <MatrixWidth>8192</MatrixWidth>
  <MatrixHeight>4096</MatrixHeight>
</TileMatrix>

Get Tiles for a Geographic Tile Matrix Set

If you intend to get the tiles coordinates for the Geographic tile matrix set, you should use the formula below:

  • x = [ (longitude + π) / (2 × π) ] × MatrixWidth
  • y = [1 - [ (latitude + π/2 ) / π ] ] × MatrixHeight

Note: latitude and longitude should be in radians.

The Geographic tile matrix set is described as follows:

  • CRS Name: urn:ogc:def:crs:OGC:1.3:CRS84 CRS84
  • Top left corner: [ -180 , 90 ]
  • Tile size: 256 × 256 pixels
Zoom level idScale DenominatorPixel Size (degrees)Pixel Size (m)*Matrix WidthMatrix Height
0279541132.01435890.70312570312.521
1139770566.00717940.35156250035156.2542
269885283.003589720.17578125017578.12584
334942641.501794868.78906250 × 10-28789.063168
417471320.750897434.39453125 × 10-24394.5313216
58735660.3754487152.19726562500 × 10-22197.2666432
64367830.1877243571.09863281250 × 10-21098.63312864
72183915.0938621795.49316406250 × 10-3549.316256128
81091957.5469310892.74658203125 × 10-3274.658512256
9545978.77346554471.37329101562500 × 10-3137.3291024512
10272989.38673277236.86645507812500 × 10-468.66520481024
11136494.69336638623.43322753906250 × 10-434.33240962048
1268247.346683193091.71661376953125 × 10-417.16681924096
1334123.673341596548.58306884765625 × 10-58.5831163848192
1417061.836670798274.29153442382812 × 10-54.29153276816384
158530.9183353991362.14576721191406 × 10-52.14586553632768
164265.4591676995681.07288360595703 × 10-51.072913107265536
172132.7295838497845.36441802978516 × 10-60.53644262144131072

* Approximation at the equator


The matrix width and height depends on the zoom level. You can pick the correct value using the table provided above. Be aware that the size of the tile matrix differs between the Geographic and the Web Mercator tile matrix set.


The request returns an XML response which is conformed to the OGC specification. By aggregating different elements such as the style, the tile matrix set with the ResourceURL value and integrating the tiles coordinates, you can access a single tile.


The below example contains the following elements which make up the url to retrieve a tile:

  • EPSG - in this example it is “EPSG4326”
  • Zoom level - in this example this is “17”
  • Upper left tile - in this example it is “41955”
  • Bottom right tile - in this example it is “38143”
curl -X GET -H "Authorization: Bearer <API_KEY>" \
 "https://view.geoapi-airbusds.com/api/v1/map/imagery.wmts?tilematrixset=4326&Service=WMTS&Request=GetTile&Version=1.0.0&Format=image/png&TileMatrix=17&TileCol=41955&TileRow=38143"
Not available.
Not available.

Here you can see the result displaying one tile:

WMTSBottomRight.png

For this example the result is made up of 9 tiles. The overall size of the composite image is 728 (3 × 256) pixels per 728 pixels (3 × 256 pixels) and the returned BBOX exceeded the initial BBOX requested.

Get Tiles for a Web Mercator Tile Matrix Set

If you intend to get the tiles coordinates for the Web Mercator tile matrix set, you will have to first reproject the coordinates to the Mercator projection (from EPSG:4326 to EPSG:3857). Then you will be required to transform the range of latitude and longitude to 0 - 1 and shift origin to top left corner:

  • n = 2 ^zoom
  • xtile = n × ((longitude + π) / (2 × π))
  • ytile = (1 - (log(tan(latitude) + sec(latitude)) / π)) / (2 × n)

Note: latitude and longitude are required in radians.

The Web Mercator tile matrix set is described as follows:

  • CRS Name: urn:ogc:def:crs:EPSG:6.18:3:3857
  • Top left corner: [ -20037508.3427892 , 20037508.3427892 ]
  • Tile size: 256 × 256 pixels
Zoom level idScale DenominatorPixel Size (m)Matrix WidthMatrix Height
0559082264.0287178156543.033928041011
1279541132.014358978271.5169640204822
2139770566.007179439135.7584820102344
369885283.0035897219567.8792410051288
434942641.501794869783.9396205025611616
517471320.750897434891.9698102512803232
68735660.3754487152445.9849051256406464
74367830.1877243571222.992452562820128128
82183915.093862179611.4962262814100256256
91091957.546931089305.7481131407048512512
10545978.7734655447152.874056570352510241024
11272989.386732772376.4370282851762420482048
12136494.693366386238.2185141425881340964096
1368247.3466831930919.1092570712940681928192
1434123.673341596549.5546285356470321638416384
1517061.836670798274.7773142678235163276832768
168530.9183353991362.3886571339117586553665536
174265.4591676995681.194328566955879131072131072
182132.7295838497840.5971642834779395262144262144

You can use the same principle explained for the geographic tile grid. You must include the following elements within the url:

  • EPSG - in this example it is “EPSG3857”
  • Zoom level - in this example this is “17”
  • Upper left tile - in this example it is “41955”
  • Bottom right tile - in this example it is “38143”
curl -X GET -H "Authorization: Bearer <API_KEY>" \
 "https://view.geoapi-airbusds.com/api/v1/map/imagery.wmts?tilematrixset=3857&Service=WMTS&Request=GetTile&Version=1.0.0&Format=image/png&TileMatrix=18&TileCol=41955&TileRow=101468"
Not available.
Not available.

Here you can see the result displaying all the 3 tiles:

WMTS3857Matrix.JPG