Map Kit Functions Reference

Framework
MapKit/MapKit.h
Companion guide
Location Awareness Programming Guide
Declared in
MKGeometry.h
MKOverlayView.h

Overview

This document describes the functions found in the Map Kit framework.

Functions by Task

The functions of the MapKit framework provide convenient ways to package map-related data structures.

Making Coordinate Structures

Making Map Point Structures

Converting Between Data Types

Getting Map Units

Getting Points Along a Map Rectangle

Comparing Map Values

Modifying Map Rectangles

Getting Strings for Map Values

Determining Map Boundaries

Functions

MKCoordinateForMapPoint

Returns the latitude and longitude that corresponds to the specified map point.

CLLocationCoordinate2D MKCoordinateForMapPoint(
   MKMapPoint mapPoint
);
Parameters
mapPoint

The map point value that corresponds to the desired point on a two-dimensional map projection.

Return Value

The coordinate structure containing the latitude and longitude values for the specified point.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
MKGeometry.h

MKCoordinateRegionForMapRect

Returns the region that corresponds to the specified map rectangle.

MKCoordinateRegion MKCoordinateRegionForMapRect(
   MKMapRect rect
);
Parameters
rect

The map rectangle that corresponds to the desired region on a two-dimensional map projection.

Return Value

The region structure specifying the latitude, longitude, and span values for the specified rectangle.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKGeometry.h

MKCoordinateRegionMake

Creates a new MKCoordinateRegion from the specified coordinate and span values.

UIKIT_STATIC_INLINE MKCoordinateRegion MKCoordinateRegionMake(
   CLLocationCoordinate2D centerCoordinate,
   MKCoordinateSpan span
);
Parameters
centerCoordinate

The center point of the region.

span

The horizontal and vertical span representing the amount of map to display. The size of the span also reflects the current zoom level.

Return Value

A region with the specified values.

Availability
  • Available in iOS 3.0 and later.
Declared In
MKGeometry.h

MKCoordinateRegionMakeWithDistance

Creates a new MKCoordinateRegion from the specified coordinate and distance values. 

MKCoordinateRegion MKCoordinateRegionMakeWithDistance(
   CLLocationCoordinate2D centerCoordinate,
   CLLocationDistance latitudinalMeters,
   CLLocationDistance longitudinalMeters
);
Parameters
centerCoordinate

The center point of the new coordinate region.

latitudinalMeters

The amount of north-to-south distance (measured in meters) to use for the span.

longitudinalMeters

The amount of east-to-west distance (measured in meters) to use for the span.

Return Value

A region with the specified values.

Availability
  • Available in iOS 3.0 and later.
Related Sample Code
Declared In
MKGeometry.h

MKCoordinateSpanMake

Creates a new MKCoordinateSpan from the specified values.

UIKIT_STATIC_INLINE MKCoordinateSpan MKCoordinateSpanMake(
   CLLocationDegrees latitudeDelta,
   CLLocationDegrees longitudeDelta
);
Parameters
latitudeDelta

The amount of north-to-south distance (measured in degrees) to use for the span. Unlike longitudinal distances, which vary based on the latitude, one degree of latitude is approximately 111 kilometers (69 miles) at all times.

longitudeDelta

The amount of east-to-west distance (measured in degrees) to use for the span. The number of kilometers spanned by a longitude range varies based on the current latitude. For example, one degree of longitude spans a distance of approximately 111 kilometers (69 miles) at the equator but shrinks to 0 kilometers at the poles.

Return Value

A span with the specified delta values.

Availability
  • Available in iOS 3.0 and later.
Declared In
MKGeometry.h

MKMapPointEqualToPoint

Returns a Boolean value indicating whether the two map points are equal.

BOOL MKMapPointEqualToPoint(
   MKMapPoint point1,
   MKMapPoint point2
);
Parameters
point1

The first map point.

point2

The second point.

Return Value

YES if the x and y values in both points are exactly the same or NO if one or both values are different.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKGeometry.h

MKMapPointForCoordinate

Returns the map point data structure that corresponds to the specified coordinate. 

MKMapPoint MKMapPointForCoordinate(
   CLLocationCoordinate2D coordinate
);
Parameters
coordinate

The coordinate containing the latitude and longitude values for the desired point.

Return Value

The map point value that corresponds to the specified coordinate on a two-dimensional map projection.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
MKGeometry.h

MKMapPointMake

Creates a new MKMapPoint structure from the specified values.

MKMapPoint MKMapPointMake(
   double x,
   double y
);
Parameters
x

The point along the east-west axis of the map projection.

y

The point along the north-south axis of the map projection.

Return Value

A map point with the specified values.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
MKGeometry.h

MKMapPointsPerMeterAtLatitude

Returns the number of map points that represent one meter at the given latitude.

double MKMapPointsPerMeterAtLatitude(
   CLLocationDegrees latitude
);
Parameters
latitude

The latitude for which to return the value.

Return Value

The number of map points that span one meter.

Discussion

The number of map points per meter increases as the latitude approaches the poles.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKGeometry.h

MKMapRectContainsPoint

Returns a Boolean value indicating whether the specified map point lies within the rectangle.

BOOL MKMapRectContainsPoint(
   MKMapRect rect,
   MKMapPoint point
);
Parameters
rect

The map rectangle being tested.

point

The point to check.

Return Value

YES if the rectangle is not null or empty and the point is located inside the rectangle; otherwise, NO.

Discussion

A point is considered to be inside the rectangle if its coordinates lie inside the rectangle or on the minimum X or minimum Y edge.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKGeometry.h

MKMapRectContainsRect

Returns Boolean value indicating whether one rectangle contains another.

BOOL MKMapRectContainsRect(
   MKMapRect rect1,
   MKMapRect rect2
);
Parameters
rect1

The containing rectangle.

rect2

The rectangle that might be contained in rect1.

Return Value

YES if rect2 is null or lies entirely inside rect1; otherwise, returns NO if rect1 is null or does not completely enclose rect2.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKGeometry.h

MKMapRectDivide

Divides the specified rectangle into two smaller rectangles.

void MKMapRectDivide(
   MKMapRect rect,
   MKMapRect *slice,
   MKMapRect *remainder,
   double amount,
   CGRectEdge edge
);
Parameters
rect

The rectangle to divide.

slice

On input, a pointer to a map rectangle. On output, this parameter contains the portion of rect that was removed.

remainder

On input, a pointer to a map rectangle. On output, this parameter contains the remaining portion of rect that was not removed.

amount

The amount of rect to remove along the specified edge. If this value is negative, it is set to 0.

edge

The edge from which to remove the specified amount.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKGeometry.h

MKMapRectEqualToRect

Returns a Boolean value indicating whether the two map rectangles are equal

BOOL MKMapRectEqualToRect(
   MKMapRect rect1,
   MKMapRect rect2
);
Parameters
rect1

The first map rectangle.

rect2

The second map rectangle.

Return Value

YES if the rectangles are exactly the same or NO if the origin point or size values are different.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKGeometry.h

MKMapRectGetHeight

Returns the height of the map rectangle.

double MKMapRectGetHeight(
   MKMapRect rect
);
Parameters
rect

The map rectangle to test.

Return Value

The rectangle’s height.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKGeometry.h

MKMapRectGetMaxX

Returns the maximum x-axis value of the specified rectangle.

double MKMapRectGetMaxX(
   MKMapRect rect
);
Parameters
rect

The map rectangle to test.

Return Value

The maximum x-axis value.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
MKGeometry.h

MKMapRectGetMaxY

Returns the maximum y-axis value of the specified rectangle.

double MKMapRectGetMaxY(
   MKMapRect rect
);
Parameters
rect

The map rectangle to test.

Return Value

The maximum y-axis value.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
MKGeometry.h

MKMapRectGetMidX

Returns the mid-point along the x-axis of the specified rectangle.

double MKMapRectGetMidX(
   MKMapRect rect
);
Parameters
rect

The map rectangle to test.

Return Value

The midpoint value along the x-axis.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
MKGeometry.h

MKMapRectGetMidY

Returns the mid-point along the y-axis of the specified rectangle.

double MKMapRectGetMidY(
   MKMapRect rect
);
Parameters
rect

The map rectangle to test.

Return Value

The midpoint value along the y-axis.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
MKGeometry.h

MKMapRectGetMinX

Returns the minimum x-axis value of the specified rectangle.

double MKMapRectGetMinX(
   MKMapRect rect
);
Parameters
rect

The map rectangle to test.

Return Value

The minimum x-axis value.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKGeometry.h

MKMapRectGetMinY

Returns the minimum y-axis value of the specified rectangle.

double MKMapRectGetMinY(
   MKMapRect rect
);
Parameters
rect

The map rectangle to test.

Return Value

The minimum y-axis value.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKGeometry.h

MKMapRectGetWidth

Returns the width of the map rectangle.

double MKMapRectGetWidth(
   MKMapRect rect
);
Parameters
rect

The map rectangle to test.

Return Value

The rectangle’s width.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKGeometry.h

MKMapRectInset

Returns the specified rectangle inset by the specified amounts.

MKMapRect MKMapRectInset(
   MKMapRect rect,
   double dx,
   double dy
);
Parameters
rect

The original rectangle.

dx

The amount (in map points) to subtract from both sides along the x-axis.

dy

The amount (in map points) to subtract from both sides along the y-axis.

Return Value

The inset rectangle. If the original rectangle was null, that rectangle is returned instead.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
MKGeometry.h

MKMapRectIntersection

Returns the rectangle representing the intersection of two rectangles.

MKMapRect MKMapRectIntersection(
   MKMapRect rect1,
   MKMapRect rect2
);
Parameters
rect1

The first rectangle.

rect2

The second rectangle.

Return Value

The rectangle representing the intersection of the two rectangles or MKMapRectNull if there is no intersection.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
MKGeometry.h

MKMapRectIntersectsRect

Returns a Boolean value indicating whether two rectangles intersect each other.

BOOL MKMapRectIntersectsRect(
   MKMapRect rect1,
   MKMapRect rect2
);
Parameters
rect1

The first rectangle to test.

rect2

The second rectangle to test.

Return Value

YES if rect1 and rect2 intersect each other or NO if they do not intersect or either rectangle is null.

Discussion

The rectangles are not considered to be intersecting if the only intersection occurs along an edge. To be considered a true intersection, the rectangles must both enclose a single rectangular area whose width and height are both greater than 0.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
MKGeometry.h

MKMapRectIsEmpty

Returns a Boolean value indicating whether the specified rectangle has no area.

BOOL MKMapRectIsEmpty(
   MKMapRect rect
);
Parameters
rect

The rectangle to test.

Return Value

YES if the rectangle is null or its width or height are equal to 0; otherwise, NO.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKGeometry.h

MKMapRectIsNull

Returns a Boolean indicating whether the specified rectangle is null.

BOOL MKMapRectIsNull(
   MKMapRect rect
);
Parameters
rect

The rectangle to test.

Return Value

YES if the rectangle is null or NO if it is not null.

Discussion

A rectangle is considered null if its origin point contains an invalid or infinite value.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
MKGeometry.h

MKMapRectMake

Creates a new MKMapRect structure from the specified values.

MKMapRect MKMapRectMake(
   double x,
   double y,
   double width,
   double height
);
Parameters
x

The point along the east-west axis of the map projection to use for the origin.

y

The point along the north-south axis of the map projection to use for the origin.

width

The width of the rectangle (measured using map points).

height

The height of the rectangle (measured using map points).

Return Value

A map rectangle with the specified values.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
MKGeometry.h

MKMapRectOffset

Returns a rectangle whose origin point is shifted by the specified amount.

MKMapRect MKMapRectOffset(
   MKMapRect rect,
   double dx,
   double dy
);
Parameters
rect

The original rectangle.

dx

The amount (in map points) by which to shift the x-coordinate of the origin point.

dy

The amount (in map points) by which to shift the y-coordinate of the origin point.

Return Value

The offset rectangle. If the original rectangle was null, that rectangle is returned instead.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKGeometry.h

MKMapRectRemainder

Normalizes the portion of the specified rectangle that lies outside the world map boundaries.

MKMapRect MKMapRectRemainder(
   MKMapRect rect
);
Parameters
rect

The rectangle to check.

Discussion

For a rectangle that lies on the 180th meridian, this function isolates the portion that lies outside the boundary, wraps it to the opposite side of the map, and returns that rectangle.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKGeometry.h

MKMapRectSpans180thMeridian

Returns a Boolean value that indicates whether the specified map rectangle crosses the 180th meridian.

BOOL MKMapRectSpans180thMeridian(
   MKMapRect rect
);
Parameters
rect

The rectangle to test.

Return Value

YES if the rectangle spans the 180th meridian or NO if it is contained wholly within the world map.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKGeometry.h

MKMapRectUnion

Returns a rectangle representing the union of the two rectangles.

MKMapRect MKMapRectUnion(
   MKMapRect rect1,
   MKMapRect rect2
);
Parameters
rect1

The first rectangle.

rect2

The second rectangle.

Return Value

A rectangle whose area encompasses the two rectangles and the space between them.

Discussion

If either rectangle is null, this method returns the other rectangle. The origin point of the returned rectangle is set to the smaller of the x and y values for the two rectangles. Similarly, the size and width of the rectangle are computed by taking the maximum x and y values and subtracting the x and y values for the new origin point.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
MKGeometry.h

MKMapSizeEqualToSize

Returns a Boolean value indicating whether the two map sizes are equal.

BOOL MKMapSizeEqualToSize(
   MKMapSize size1,
   MKMapSize size2
);
Parameters
size1

The first map size.

size2

The second map size.

Return Value

YES if the width and height values in both sizes are exactly the same or NO if one or both values are different.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKGeometry.h

MKMapSizeMake

Creates a new MKMapSize structure from the specified values.

MKMapSize MKMapSizeMake(
   double width,
   double height
);
Parameters
width

The distance (measured using map points) along the east-west axis of the map projection.

height

The distance (measured using map points) along the north-south axis of the map projection.

Return Value

A map size with the specified values.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKGeometry.h

MKMetersBetweenMapPoints

Returns the number of meters between two map points.

CLLocationDistance MKMetersBetweenMapPoints(
   MKMapPoint a,
   MKMapPoint b
);
Parameters
a

The first map point.

b

The second map point.

Return Value

The number of meters between the specified map points.

Discussion

This distance reflects the actual distance between the two points on the surface of the globe, taking into account the curvature of the Earth.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
MKGeometry.h

MKMetersPerMapPointAtLatitude

Returns the distance spanned by one map point at the specified latitude.

CLLocationDistance MKMetersPerMapPointAtLatitude(
   CLLocationDegrees latitude
);
Parameters
latitude

The latitude for which to return the value.

Return Value

The distance (in meters) spanned by a single map point.

Discussion

The distance between map points decreases as the latitude approaches the poles. This relationship parallels the relationship between longitudinal coordinates at different latitudes.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKGeometry.h

MKRoadWidthAtZoomScale

Returns the width (in screen points) of roads on a map at the specified zoom level.

CGFloat MKRoadWidthAtZoomScale(
   MKZoomScale zoomScale
);
Parameters
zoomScale

The scale factor currently applied to the map view.

Return Value

The width of roads, measured in screen points. You can use the returned value to set the width of lines in drawing code that traces the path of a road.

Special Considerations

You should not use this function to retrieve road widths in iOS 6 and later.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
MKOverlayView.h

MKStringFromMapPoint

Returns a formatted string for the specified map point.

NSString *MKStringFromMapPoint(
   MKMapPoint point
);
Parameters
point

The map point to format.

Return Value

A formatted string containing the x and y coordinates of the map point.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKGeometry.h

MKStringFromMapRect

Returns a formatted string for the specified map rectangle.

NSString *MKStringFromMapRect(
   MKMapRect rect
);
Parameters
rect

The map rectangle to format.

Return Value

A formatted string containing the origin and size values of the map rectangle.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKGeometry.h

MKStringFromMapSize

Returns a formatted string for the specified map size.

NSString *MKStringFromMapSize(
   MKMapSize size
);
Parameters
size

The map size to format.

Return Value

A formatted string containing the width and height values of the map size.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKGeometry.h


© 2010 Apple Inc. All Rights Reserved. (Last updated: 2010-05-11)

Did this document help you? Yes It's good, but... Not helpful...