Getting a Bing Maps API key

The first thing you need before connecting to the Bing Maps servers is a Bing Maps API key. On the Bing Maps portal, you can create a Bing Maps account and one or more Bing Maps keys.

To request a Bing Maps key from Microsoft:

  1. Go to http://www.bingmapsportal.com.

  2. Sign in with your Microsoft account, or create one.

  3. Click "Create or view keys".

  4. Choose "Evaluation / Trial" and click Submit.
    The Bing Maps portal creates the key.

Note that additional terms may apply for deployment. For more information on Bing Maps licensing, see the Licensing information guide.

Visualizing Bing Maps data

The Bing Maps protocol requires the retrieval of metadata containing the URLs of the services that provide the imagery. Due to cross-domain restrictions, the LuciadRIA samples use a bingproxy sample service that forwards the metadata requests to the official service.

An extra advantage of using a proxy is that you can configure the required Bing key on the server side, and avoid exposing it to your users. You can configure the key either through the environment variable LUCIAD_RIA_BING_KEY, or through an initialization parameter in the servlet web.xml with the name bing.key.

The servlet is available as sample code. You can have a look at com.luciad.samples.webservices.bingproxy.BingProxyServlet in the samples source code folder, to see the available options, or to adapt it to your needs.

If the bingproxy servlet is running, you can use it to retrieve the metadata to set up a BingMapsTileSetModel. You can visualize this model in a regular RasterTileSetLayer, as illustrated in this example:

Program: Creating a Bing Maps raster layer using the sample BingProxyServlet (from samples/dataformats/loaders/BingMapsDataLoader.js) 
const layer = fetch(`/sampleservices/bingproxy/${type}`)
    .then(response => response.json())
    .catch(() => {
      throw new Error(
          "Something went wrong while contacting the Bing proxy. Did you configure it with a Bing Maps key?"
      )
    }).then(data => {
      let resource;
      if (data.resourceSets[0] && data.resourceSets[0].resources[0]) {
        resource = data.resourceSets[0].resources[0];
        resource.brandLogoUri = data.brandLogoUri;
      } else {
        resource = data;
      }
      const model = new BingMapsTileSetModel(resource);
      return new RasterTileSetLayer(model, {
        label: `${type} (Bing)`,
        layerType: LayerType.BASE,
        id: "Background"
      });
    });

Another aspect of using Bing Maps background data is that you are required to show the attribution information of the imagery.

The LuciadRIA sample code contains an Attribution overlay component to handle this.

Please refer to the sample samples/common/ui/overlay/Attribution.tsx for more details.

Program: Including Bing Maps attribution information using the sample component Attribution (from samples/common/ui/overlay/Attribution.tsx) 
export const Attribution = ({map, separator = " • ", staticAttributions}: Props) => {

  const [layerAttributions, setLayerAttributions] = useState<LayerAttribution[]>([]);

  useEffect(() => {
    const attributionProvider = new TileSetAttributionProvider(map);

    const layerAttributionListener = attributionProvider.on("LayerAttributionsChanged", (layerAttributions) => {
      setLayerAttributions(layerAttributions);
    });

    setLayerAttributions(attributionProvider.getLayerAttributions())

    return () => {
      layerAttributionListener.remove();
    }
  }, [map]);

  // if multiple layers provide attribution, add the layer label to the line, so you know what attributions belong to what layer
  const showLayerLabel = layerAttributions.length > 1;

  return (
      <div className="attribution">
        <div className="attribution-strings">
          {layerAttributions.map(attr =>
              <div key={attr.layer.id}>
              {(showLayerLabel ? `[${attr.layer.label}]: ` : "")}
                {attr.attributionStrings.join(separator)}
                {(attr.attributionLogos as string[]).map(
                    logo => <img className="attributionLogo" alt={logo} key={logo} src={logo}/>)}
              </div>
          )}
          {staticAttributions}
        </div>
      </div>
  )
}