Guides and Sample Code

Developer

Apple News Format: Design Tutorial

On This Page

Map Components

You can use map components or place components to embed maps in an article. In this tutorial, you’ll use a map component. By including visual, geographic information in your article, you can help your users contextualize information.

image: ../Art/map-closeup_2x.png
image: ../Art/map_2x.png

You’ll add a map component in the article’s components array. You’ll use latitude and longitude properties to determine where the map is centered. If you don’t add latitude and longitude properties, the map center will be automatically determined based on pins.

Next, you’ll use the span property to control the size of the area that the map covers.

Finally, you’ll create a caption for a pin.

For information on customizing maps, see Map, Place, and Map Item in the Apple News Format Reference.

JSON Example: Map Component

Create a heading2 component and a map component that is centered at specific coordinates.

Example Code

Ellipses (...) indicate lines of code that have been omitted from this example.

  1. {
  2. ...
  3. "components": [
  4. ...
  5. {
  6. "role": "heading2",
  7. "layout": "fullMarginAboveHalfBelowLayout",
  8. "text": "MAP HEADING"
  9. },
  10. {
  11. "role": "map",
  12. "layout": "noMarginLayout",
  13. "mapType": "hybrid",
  14. "latitude": 35.065908,
  15. "longitude": -109.781623
  16. },
  17. ...
  18. ],
  19. ...
  20. }

JSON Example: span Property

Use the map’s span property to adjust the size of the visible area. A span is the distance between the center and edge of the map. These distances are specified as latitudeDelta (between 0 and 90) and longitudeDelta (between 0 and 180). For more details, see Map in the Apple News Format Reference.

Example Code

Ellipses (...) indicate lines of code that have been omitted from this example.

  1. {
  2. ...
  3. "components": [
  4. ...
  5. {
  6. "role": "map",
  7. "layout": "noMarginLayout",
  8. "mapType": "hybrid",
  9. "latitude": 35.065908,
  10. "longitude": -109.781623,
  11. "span": {
  12. "latitudeDelta": 5,
  13. "longitudeDelta": 5
  14. }
  15. },
  16. ...
  17. ],
  18. ...
  19. }

JSON Example: Map Pin

Add a pin, or map item, to the map. Pins are objects that are located in the map component’s items array. For more information about pins, see Map Item in the Apple News Format Reference.

Unlike other arrays in Apple News Format, the order of items in the map component’s items array is not important.

image: ../Art/map-pin_2x_2x.png

Example Code

Ellipses (...) indicate lines of code that have been omitted from this example.

  1. {
  2. ...
  3. "components": [
  4. ...
  5. {
  6. "role": "map",
  7. "layout": "noMarginLayout",
  8. "mapType": "hybrid",
  9. "latitude": 35.065908,
  10. "longitude": -109.781623,
  11. "span": {
  12. "latitudeDelta": 5,
  13. "longitudeDelta": 5
  14. },
  15. "items": [
  16. {
  17. "latitude": 35.065908,
  18. "longitude": -109.781623
  19. }
  20. ]
  21. },
  22. ...
  23. ],
  24. ...
  25. }

JSON Example: Captioned Pin

Add a caption to the pin. When the user taps the pin in the full-screen version of the map, the caption is displayed. The caption can also be used by VoiceOver for iOS.

image: ../Art/map-pin-caption_2x_2x.png

Example Code

Ellipses (...) indicate lines of code that have been omitted from this example.

  1. {
  2. ...
  3. "components": [
  4. ...
  5. {
  6. "role": "map",
  7. "layout": "noMarginLayout",
  8. "mapType": "hybrid",
  9. "caption": "Map caption",
  10. "latitude": 35.065908,
  11. "longitude": -109.781623,
  12. "span": {
  13. "latitudeDelta": 5,
  14. "longitudeDelta": 5
  15. },
  16. "items": [
  17. {
  18. "caption": "A caption for this map pin",
  19. "latitude": 35.065908,
  20. "longitude": -109.781623
  21. }
  22. ]
  23. },
  24. ...
  25. ],
  26. ...
  27. }

Further Exploration

At any time, you can try changing property values in your article.json file, and then use News Preview to see how these changes impact the look of your article.

For example, try using a standard map instead of the hybrid map that includes satellite images:

  1. In your code, find the map component.

  2. Replace the value of the component’s mapType property, "hybrid", with "standard".

  3. Preview your article.json file in News Preview. See also: Updating Your Article Preview.

    The map now shows the standard map instead of the hybrid map.