wayback-core

This package offers core functionalities to retrieve all versions of the World Imagery Wayback archive, or find versions that contain local changes. It is the underlying library used by the Esri World Imagery Wayback App.

Table of Contents

• Installation
• API Documentation
  • getWaybackItems
  • getWaybackItemsWithLocalChanges
  • getMetadata
  • getWaybackServiceBaseURL
  • setCustomWaybackConfig
• Type Definitions
  • WaybackItem
  • WaybackMetadata
• Issues
• Contributing
• Licensing

Installation

Install the package using npm with the command below:

npm install @esri/wayback-core

API Documentation

getWaybackItems

Return a list of WaybackItem for all World Imagery Wayback releases/versions from the Wayback archive. The output list is sorted by release date in descending order (newest release is the first item).

Parameters:
None

Returns:

Example:

import {
    getWaybackItems,
} from '@esri/wayback-core';

const waybackItems = await getWaybackItems();

Here is an example of the response returned by getWaybackItems():

[
    {
        "itemID":"f5f90c7419f24ceda396088f4e39ae83",
        "itemTitle":"World Imagery (Wayback 2023-12-07)",
        "itemURL":"https://wayback.maptiles.arcgis.com/arcgis/rest/services/World_Imagery/WMTS/1.0.0/default028mm/MapServer/tile/56102/{level}/{row}/{col}",
        "metadataLayerUrl":"https://metadata.maptiles.arcgis.com/arcgis/rest/services/World_Imagery_Metadata_2023_r11/MapServer",
        "metadataLayerItemID":"be19e857134046638a10dc2886a5398b",
        "layerIdentifier":"WB_2023_R11",
        "releaseNum":56102,
        "releaseDateLabel":"2023-12-07",
        "releaseDatetime": 1701936000000,
    },
    //...
]

getWaybackItemsWithLocalChanges

Return a list of WaybackItem with local changes for a specified geographic point at a given zoom level.

Parameters:

Returns:

Example:

import { 
    getWaybackItemsWithLocalChanges 
} from '@esri/wayback-core';

const waybackItems = await getWaybackItemsWithLocalChanges(
    {
        longitude: 117.1825,
        latitude: 34.0556,
    },
    15
);

Example with options:

const controller = new AbortController();

const waybackItems = await getWaybackItemsWithLocalChanges(
    {
        longitude: 117.1825,
        latitude: 34.0556,
    },
    15,
    {
        signal: controller.signal,
        onlyUseSizeToFilterDuplicates: true,
    }
);

Here is an example of the response returned by getWaybackItemsWithLocalChanges():

[
    {
        "itemID":"f5f90c7419f24ceda396088f4e39ae83",
        "itemTitle":"World Imagery (Wayback 2023-12-07)",
        "itemURL":"https://waybackdev.maptiles.arcgis.com/arcgis/rest/services/World_Imagery/WMTS/1.0.0/default028mm/MapServer/tile/56102/{level}/{row}/{col}",
        "metadataLayerUrl":"https://metadatadev.maptiles.arcgis.com/arcgis/rest/services/World_Imagery_Metadata_2023_r11/MapServer",
        "metadataLayerItemID":"be19e857134046638a10dc2886a5398b",
        "layerIdentifier":"WB_2023_R11",
        "releaseNum":56102,
        "releaseDateLabel":"2023-12-07",
        "releaseDatetime": 1701936000000,
    },
    //...
]

getMetadata

Query the wayback metadata feature service associated with the given wayback release/version to retrieve information (acquisition date, provider, resolution, etc.) of the world imagery wayback tile image at the specified location and zoom level.

Parameters:

Returns:

Example:

import { getMetadata } from '@esri/wayback-core';

const metadata = await getMetadata(
    {
        longitude: 117.1825,
        latitude: 34.0556,
    },
    15,
    56102,
);

Example with options:

const controller = new AbortController();

const metadata = await getMetadata(
    {
        longitude: 117.1825,
        latitude: 34.0556,
    },
    15,
    56102,
    {
        signal: controller.signal,
    }
);

Here is an example of the response returned by getMetadata():

{
    "date": 1680307200000, 
    "provider": 'Maxar', 
    "source": 'WV03', 
    "resolution": 0.3, 
    "accuracy": 5
}

getWaybackServiceBaseURL

Returns the base URL for the Wayback service, with a randomly selected subdomain.

Parameters: None

Returns:

Example:

import { getWaybackServiceBaseURL } from '@esri/wayback-core';

const baseURL = getWaybackServiceBaseURL();
console.log(baseURL);
// Example output: "https://wayback.maptiles.arcgis.com/arcgis/rest/services/World_Imagery/MapServer"

setCustomWaybackConfig

Configure custom wayback settings for testing or development purposes. This allows you to override the default Wayback configuration with custom subdomains, configuration file URLs, or configuration data.

Parameters:

Returns:

Example:

import { setCustomWaybackConfig } from '@esri/wayback-core';

// Example 1: Set custom subdomains and configuration file URL
setCustomWaybackConfig({
    subDomains: ['custom-wayback-1', 'custom-wayback-2'],
    waybackConfigFileURL: 'https://example.com/custom-wayback-config.json'
});

// Example 2: Set custom configuration data directly
setCustomWaybackConfig({
    waybackConfigData: {
        '12345': {
            itemID: 'custom-item-id',
            itemTitle: 'World Imagery (Wayback 2024-01-15)',
            itemURL: 'https://custom.url/tile/12345/{level}/{row}/{col}',
            metadataLayerUrl: 'https://custom.metadata.url/MapServer',
            metadataLayerItemID: 'custom-metadata-id',
            layerIdentifier: 'WB_2024_R01',
        }
    }
});

Type Definitions

WaybackItem

Object that represents a specific release/version of the World Imagery Wayback archive.

Usage:

import { WaybackItem } from '@esri/wayback-core';

Properties:

WaybackMetadata

This object represents the metadata of a Wayback tile image.

Usage:

import { WaybackMetadata } from '@esri/wayback-core';

Properties:

Issues

Find a bug or want to request a new feature? Please let us know by submitting an issue.

Contributing

Esri welcomes contributions from anyone and everyone. Please see our guidelines for contributing.

Licensing

The Imagery

The imagery presented in the Wayback Archive is subject to the terms and conditions set forth in the Esri Master Agreement or Terms of Use. See World Imagery for additional details on the imagery content and applicable Terms of Use.

The Software

Copyright 2023 Esri

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

A copy of the license is available in the repository's LICENSE file.