Elevation Layers (1.0.0)

Download OpenAPI specification:Download

Introduction

The elevation layers API offers up to date tiles for elevation data and derivatives.

Attribution

The layers provided by Clockwork Micro make use of publicly available datasets that must be recognized with proper attribution. The documentation for each service provided by Clockwork Micro includes an attribution section. Users of each Clockwork Micro service are expected to include the required attribution.

Authentication

oAuth2ClientCredentials

See oauth2 documentation

Security Scheme Type OAuth2
clientCredentials OAuth Flow
Token URL: https://auth.clockworkmicro.com/oauth2/token
Scopes:

    x-api-key

    api key required if not providing oAuth token.

    Security Scheme Type API Key
    Header parameter name: x-api-key

    terrainlayers

    Get underlying and processed terrain data

    Retrieves a png tile for the given layer and processing values

    Produces png tiles based on terrain data, for the given values.

    The service is primary built using the gdaldem library of the Geospatial Data Abstraction Library. The underlying data is the Terrain Tiles hosted by the Registry of Open Data on AWS.

    The Clockwork Micro Terrain Tiles are built based on the terrain tiles developed by Tilezen. Attribution is required when using the Terrain Tiles and must satisfy the Attribution documentation provided by Tilezen.

    path Parameters
    z
    required
    integer
    Example: 14

    z coordinate of the tile

    x
    required
    integer
    Example: 2610

    x coordinate of the tile

    y
    required
    integer
    Example: 5667

    y coordinate of the tile

    query Parameters
    transform_type
    string
    Enum: "hillshade" "aspect" "slope" "raw"
    Example: transform_type=hillshade

    the type of transform to apply to the underlying tile. If none passed, defaults to "raw".

    relief
    string
    Example: relief=25%2060%2060%2060%0A50%20130%20130%20130%0A75%20200%20200%20200%0A100%20255%20255%20255

    optional colour relief to apply, sent as newline-separated gradient, the example given below is for the relief profile

    25 60 60 60
    50 130 130 130
    75 200 200 200
    100 255 255 255
    scale_params
    string
    Example: scale_params=0,359,0,255

    optional set of scale parameters to map input values to output values for the raw transform. e.g. 0,359,0,255 will normalise values from the input tile into 0-255 in the output.

    These scale values will be used for the raw (default) transform; but can also be passed for "aspect" and "slope" transforms.

    Responses

    Request samples

    from oauthlib.oauth2 import BackendApplicationClient
    from requests_oauthlib import OAuth2Session
    from requests.auth import HTTPBasicAuth
    
    url_to_fetch = 'https://layer.clockworkmicro.com/v1/terrainlayers?z=14&x=2622&y=5719&transform_type=hillshade'
    token_url = 'https://auth.clockworkmicro.com/oauth2/token'
    
    # replace with your client id and secret
    client_id = ''
    client_secret = ''
    
    # authorise with oauth client credentials flow
    auth = HTTPBasicAuth(client_id, client_secret)
    client = BackendApplicationClient(client_id=client_id)
    oauth = OAuth2Session(client=client)
    token = oauth.fetch_token(token_url=token_url, client_secret=client_secret, auth=auth)
    
    response = oauth.get(url_to_fetch)
    
    with open('output.png', 'wb') as f:
        f.write(response.content)
    

    webtileboundaries

    Get tiles showing coordinates

    Retrieves a png tile showing coordinates

    Produces png tiles showing the coordinates of the given tile.

    Accepts parameters to configure styling.

    query Parameters
    border-color
    string
    Default: 0
    Example: border-color=FF0000

    colour of the tile border (html colour)

    border-width
    integer
    Default: 2
    Example: border-width=1

    width of the tile border

    font-size
    int
    Default: 16
    Example: font-size=8

    size of the font (px)

    text-color
    string
    Default: 0
    Example: text-color=FF0000

    colour of the text (html colour)

    text-stroke-color
    string
    Default: "FFFFFF"
    Example: text-stroke-color=FF0000

    colour of the text stroke (html colour)

    Responses

    Request samples

    import requests
    url_to_fetch = 'https://layer.clockworkmicro.com/v1/webtileboundaries?border-color=00FF00'
    response = requests.get(url_to_fetch)
    
    with open('output.png', 'wb') as f:
        f.write(response.content)
    

    streets

    Get map or tiles for base map

    Retrieves a base map showing street tiles

    query Parameters
    lat
    number
    Example: lat=40

    latitude at which to centre the map

    lng
    number
    Example: lng=-80

    longitude at which to centre the map

    z
    integer
    Default: 12
    Example: z=5

    zoom level of map

    Retrieves vector tiles for the base map

    path Parameters
    z
    required
    integer
    Example: 14

    z coordinate of the tile

    x
    required
    integer
    Example: 2610

    x coordinate of the tile

    y
    required
    integer
    Example: 5667

    y coordinate of the tile

    Retrieves raster tiles for the base map

    path Parameters
    z
    required
    integer
    Example: 14

    z coordinate of the tile

    x
    required
    integer
    Example: 2610

    x coordinate of the tile

    y
    required
    integer
    Example: 5667

    y coordinate of the tile

    elevation

    Get elevation of a point

    Retrieves elevation given a lat lng coordinate.

    query Parameters
    lat
    number
    Example: lat=40

    latitude

    lng
    number
    Example: lng=-80

    longitude

    request_type
    string
    Default: "elevation"
    Enum: "elevation" "elevation_geoid" "geoid"

    the type of elevation data to return

    • elevation returns elevation against mean sea level (MSL)
    • elevation_geoid returns elevation against the WGS84 geoid
    • geoid returns the difference between the elevation at MSL and the WGS84 geoid

    Responses

    Request samples

    curl "https://elevation.clockworkmicro.com/v1/elevation?lat=40&lng=-80&request_type=elevation&x-api-key=<YOUR API KEY>"
    

    Response samples

    Content type
    application/json
    276.36

    Retrieves elevations given lat lng coordinates.

    query Parameters
    request_type
    string
    Default: "elevation"
    Enum: "elevation" "elevation_geoid" "geoid"

    the type of elevation data to return

    • elevation returns elevation against mean sea level (MSL)
    • elevation_geoid returns elevation against the WGS84 geoid
    • geoid returns the difference between the elevation at MSL and the WGS84 geoid
    Request Body schema: application/json
    Array ()
    lat
    number
    lng
    number

    Responses

    Request samples

    Content type
    application/json
    [
    • {
      }
    ]

    Response samples

    Content type
    application/json
    [
    • 276.36
    ]

    USGS Topo

    Retrieves a USGS topo tile for the given layer and processing values

    Produces png tiles based on the USGS tiles, for the given values.

    The Clockwork Micro USGS Topo Map Layer is simply a delivery of the topographic maps created by the US Geological Survey, and the US Geological Survey must be acknowledged or credited in any use of the Clockwork Micro USGS Topo Map Layer. Users of the Clockwork Micro USGS Topo Map Layer are required to satisfy the Acknowledging or Crediting policy of the US Geological Survey.

    path Parameters
    z
    required
    integer
    Example: 14

    z coordinate of the tile

    x
    required
    integer
    Example: 2610

    x coordinate of the tile

    y
    required
    integer
    Example: 5667

    y coordinate of the tile

    Responses

    Request samples

    from oauthlib.oauth2 import BackendApplicationClient
    from requests_oauthlib import OAuth2Session
    from requests.auth import HTTPBasicAuth
    
    url_to_fetch = 'https://topo.clockworkmicro.com/v2/14/2610/5667.png'
    token_url = 'https://auth.clockworkmicro.com/oauth2/token'
    
    # replace with your client id and secret
    client_id = ''
    client_secret = ''
    
    # authorise with oauth client credentials flow
    auth = HTTPBasicAuth(client_id, client_secret)
    client = BackendApplicationClient(client_id=client_id)
    oauth = OAuth2Session(client=client)
    token = oauth.fetch_token(token_url=token_url, client_secret=client_secret, auth=auth)
    
    response = oauth.get(url_to_fetch)
    
    with open('output.png', 'wb') as f:
        f.write(response.content)