INRIX documentation logo

Geographies are regions that are defined by one or more polygons whose vertices are a series of latitude and longitude coordinates. They are used to limit the traffic data that is returned to be within the boundaries of the polygons, providing a more precise region than a box or a circle. Geographies can be used to define regions such as countries, states, provinces, and cities. Common predefined geographies are provided, but you can also create your own user-defined geographies. Some potential uses for geographies include:

The image below illustrates how traffic data is limited to the U.S. state of Massachusetts.

Traffic limited to the state of Massachusetts



Geography Definition

Geographies are defined using a subset of the Geography Markup Language (GML) Open Standard Simple Features Profile. GML is an XML grammar for defining geographical features, primarily through polygons and lines whose vertices are defined by longitude and latitude. The GML in geographies is limited to how SQL Server 2008 supports GML, but does not include points, lines or polylines. Simple polygons are defined by a list of latitude/longitude coordinates, where the border of the polygon is defined by connecting the coordinate points. A geography can be one polygon or multiple disjointed polygons (with or without inner rings that consist of areas that are not included), where the outside perimeters are defined in counterclockwise order, and a closed polygon is indicated by having the final point in the list be the same as the first point in the list. A full list of limitations can be found in the User-Defined Geographies section below. The images below illustrate a simple polygon, multiple polygons, and a polygon with inner rings.

     
Simple polygon
Multiple polygons
Inner rings
Simple polygon: the city of Seattle Multiple polygons: the city of Seattle and some neighboring suburbs Polygon with three inner rings: the Puget Sound area minus areas around the cities of Seattle, Tacoma, and Olympia

Note: It is important to realize that the points of the polygon are joined with the great circle path that represents the shortest line between the two points on the earth’s surface. This is not necessarily the same path as the straightest line on a given two-dimensional map. For example, the northern border of the United States follows the 49th parallel from Washington to Minnesota. On many maps (those that use Mercator projection), that border appears to follow a straight line. However, the 49th parallel is not a great circle; it is a smaller circle that runs parallel to the equator. This means that if only the two end points are used to define that border, the resulting geography would curve up to include a portion of southern Canada. (See image below.) The solution is to include several points along the 49th parallel.

Map showing great circle on U.S.'s Northern border



Geography Functionality

Geographies can be used as input to specify regions with the following requests:

API Name Description
GetXDIncidentsInGeography Retrieves XD traffic-related incidents in a specified region.
GetSegmentSpeedInGeography Retrieves road speed and congestion data for a specified geography.
GetTrafficCamerasInGeography Retrieves a set of unique traffic camera identifiers within a specified geography.
GetSegmentsInGeography Retrieves segments within a specified geography.

Note: For requests that return TMC information (GetSegmentsInGeography, etc.), if a TMC crosses the boundary of a geography so that part of it is inside and part of it is outside, then it is considered within the geography and will be included in the output. In general, geography requests return error codes with statusId of 10 if an existing geography cannot be found, or 980 if new GML is invalid.

Pre-Defined Geographies

INRIX provides a large number of pre-defined geographies that cover commonly-used boundaries. These include many countries, as well as smaller regions (states, cities, etc.) in Europe and North America. To see a full list of pre-defined geographies and their IDs, call GetGeography with the geoID set to -3, as follows:

http://{serverPath}/traffic/inrix.ashx?action=GetGeography&geoid=-3&token={token}

where {serverPath} is the path returned when requesting an authorization token, and {token} is the authorization token. This will return a list of predefined geographies and their GeoIDs, but not their GML data. The return value looks like this:

<Inrix docType="GetGeography" copyright="Copyright INRIX Inc."
  versionNumber="3.4.0" createdDate="2010-08-16T20:36:43Z"
  statusId="0" statusText=""
  responseId="4756d528-d983-4255-ae37-b8fa11317c3d">
  <Geography id="2" name="Austria"
    description="Type: Country Name: Austria Country: AUT"
    private="false" />
  <Geography id="3" name="Belgium"
    description="Type: Country Name: Belgium Country: BEL"
    private="false" />
  <Geography id="4" name="Canada"
    description="Type: Country Name: Canada Country: CAN"
    private="false" />
...
  <Geography id="265" name="Kentucky"
    description="Type: State Name: Kentucky Country: USA"
    private="false" />
  <InputParameters>
    <InputParameter name="action" value="getgeography" />
    <InputParameter name="geoid" value="-3" />
    <InputParameter name="token" value="<token>" />
  </InputParameters>
</Inrix>


User-Defined Geographies

INRIX also allows you to define your own Geographies. The idea is that you create a geography once and then use it often, referring to it by its GeoID. Standard CRUD (Create, retrieve, update, and delete) calls are provided for creating and managing your geographies: CreateGeography, GetGeography, UpdateGeography, and DeleteGeography. To create a geography, use the CreateGeography call. Specify polygon points in a counter-clockwise direction. Be aware that a geography whose polygons contain a large number of vertices will take minutes to create. Note: Geographies are cached on multiple servers. This means that when an update is made, it may take up to an hour for the change to propagate to other servers. For cases where this caching is problematic, use DeleteGeography, and then CreateGeography again, rather than UpdateGeography. The following are limitations on geographies:

Public and Private Geographies

When you create a geography, you can specify it as public or private. Public geographies can be read by others, and private geographies are only accessible by you. Use GetGeography to retrieve information on geographies that are available to your vendor, including INRIX predefined geographies.

Performance vs. Precision

The more fine-grained you define your geography, the more points you will need. However, large numbers of points will slow performance. You will see this when you create geography, and also when you retrieve information that uses longitude/latitude information instead of TMCs, such as GetTrafficCamerasInGeography. If you are using your geography to get data using INRIX XD segments or TMCs (GetSegmentSpeedInGeography, GetSegmentsInGeography, and GetTrafficCamerasInGeography), then the appropriate TMCs are already cached, and you will not see a performance effect with geographies that have more points. When defining a geography, some tools will provide more points than are needed. Smooth the border in order to reduce the points. Tools are available to reduce the number of points and improve performance, such as SQL Server 2008 Performance Improvements Methods. If your geography borders on water, then you can simply replace the detailed border that’s on the water with a small number of points that extend out into the water; since there are no roads in the water, this will not affect the accuracy of the returned data.

   
Island defined by many points
Island defined by few points
Island geography defined with many points on its shores. Island geography defined just as effectively with a small number of points in water where there are no roads.

Description: Standard CRUD (Create, retrieve, update, and delete) calls are provided for creating and managing your geographies.

/?Action=CreateGeography

POST Creates a geography and returns the ID of that geography. The ID can be saved for re-use in later requests.

Parameters

  = required
Name Located In Type Description
action Query String Use CreateGeography
token Query String A valid authorization token returned in response to a GetSecurityToken request.
name Path String The name of the geography.
private Path Boolean Specifies whether the geography is private and cannot be viewed or used by any other vendor.
Value Description
true The geography cannot be viewed or used by any other vendor.
false (default) The geogrpahy can be viewed and used by other vendors in the same vendor group. It cannot be viewed or used by any vendors in another vendor group.
description Query String A textual description of the geography.

Notes

The GML in the request body must define either a polygon or multiple polygons in order to be accepted by the system. The outside perimeters of the polygons must be defined in counterclockwise order and the first point should be the same as the last point. There are several restrictions on acceptable polygons, such as a maximum limit of 10,000 vertices. See Geographies for more information on restrictions on what polygons are acceptable.

Names are limited to 50 characters and descriptions are limited to 500 characters. If they exceed those limits, they will be truncated.

When a geography is created it make take several hours for supporting files to be created to allow for fast processing of geography calls. During this time geography calls may return failures.


Requests

Example CreateGeography request
Query
/?Action=CreateGeography&Name=GeographySampleName&Description=Geography%20Sample%20Description&Private=false&Token={token}
Body
<Polygon xmlns="http://www.opengis.net/gml">
  <exterior>
    <LinearRing>
      <posList>
    47.65 -122.27 47.63 -122.27 47.63 -122.25 47.65 -122.25 47.65 -122.27
      </posList>
    </LinearRing>
  </exterior>
</Polygon>

Responses

200 Success
<Inrix docType="CreateGeography" copyright="Copyright INRIX Inc."
    versionNumber="3.4.0" createdDate="2010-08-18T21:52:59Z" statusId="0"
    statusText="" responseId="c686c403-258a-43ce-bf50-c3bb922aee5f">
    <Geography id="10003" />
</Inrix>
980 (1) Error: Invalid GML. For example, not having an area greater than zero.
statusText: Invalid GML document.
980 (2) Error: Area of polygon is too large. Often this is due to defining the points in a clockwise direction, thereby accidentally defining the area outside the defined polygon.
statusText: GML exceeds size restrictions

/?Action=GetGeography

GET Retrieves the specified geography, or a list of geography IDs.

Parameters

  = required
Name Located In Type Description
action Query String Use GetGeography
token Query String A valid authorization token returned in response to a GetSecurityToken request.
geoId Path String The ID of the geography to be retrieved. Values -3 to 0 are reserved to return lists of geography IDs, as described in the notes below. If no GeoId is specified, then the default is -1.

Notes

GetGeography is used for two purposes:

  1. Using reserved GeoIDs with values zero or less (see table below), it returns lists of geography IDs, names, and descriptions for geographies that are available for you to use.
  2. Using GeoIDs with values greater than zero, it returns name, description, whether it is public or private, and the GML data that describes the polygons

The following table describes the reserved IDs, which return lists of geography IDs, names, and descriptions rather than the full geography data that includes the GML.

GeoIdDescription
0 All of your vendor’s public and private geographies.
-1 (default) All of your vendor’s geographies, plus all public geographies in your vendor group.
-2 All of your vendor’s geographies, plus all public geographies in your vendor group, plus INRIX predefined geographies.
-3 INRIX predefined geographies only.

Once you have obtained the geography IDs using the reserved IDs, then you may set the geoID to the obtained ID to retrieve the full data, including the GML.


Requests

Example GetGeography Request to Obtain Information on Available Geographies
Query
http://{serverPath}.INRIX.com/traffic/Inrix.ashx?Action=GetGeography&GeoId=-3&Token={token}

Responses

200 Success
<Inrix docType="GetGeography" copyright="Copyright INRIX Inc." versionNumber="3.4.0" createdDate="2010-08-16T20:36:43Z" statusId="0" statusText="" responseId="4756d528-d983-4255-ae37-b8fa11317c3d">
    <Geography id="2" name="Austria" description="Type: Country Name: Austria Country: AUT" private="false" />
    <Geography id="3" name="Belgium" description="Type: Country Name: Belgium Country: BEL" private="false" />
    <Geography id="4" name="Canada" description="Type: Country Name: Canada Country: CAN" private="false" />
    <Geography id="265" name="Kentucky" description="Type: State Name: Kentucky Country: USA" private="false" />
    <InputParameters>
        <InputParameter name="action" value="getgeography" />
        <InputParameter name="geoid" value="-3" />
        <InputParameter name="token" value="<token>" />
    </InputParameters>
</Inrix>

Response Elements

Property Type Description
Geography Element Represents a collection of traffic cameras.
Property Type Description
id Attribute (integer) Unique ID of the geography.
name Attribute (string) Name of the geography.
description Attribute (string) Description of the geography.
private Attribute (boolean) Specifies whether the geography is private and cannot be viewed or used by any other vendor.
10 Error: Geography ID does not correspond to a geography that belongs to your vendor.
statusText: Geography not found

/?Action=UpdateGeography

POST Updates a geography with new data.

Parameters

  = required
Name Located In Type Description
action Query String Use UpdateGeography
token Query String A valid authorization token returned in response to a GetSecurityToken request.
geoId Path Integer The ID of the geography to be updated.
name Path String The name of the geography.
private Path Boolean Specifies whether the geography is private and cannot be viewed or used by any other vendor.
Value Description
true The geography cannot be viewed or used by any other vendor.
false (default) The geogrpahy can be viewed and used by other vendors in the same vendor group. It cannot be viewed or used by any vendors in another vendor group.
description Query String A textual description of the geography.

Notes

You may use UpdateGeography to change the name and/or the description without changing the GML. To do this, simply do not include a request body.

You may only update a geography that belongs to your vendor.
While all geography attributes parameters other than GeoId are optional, a request with only the GeoId will return an error indicating the request is incomplete. Any of the geography attributes not included in the update request will not be changed.

When new GML is provided, it must conform to the same limitations as for CreateGeography.

Geographies are cached on multiple servers. This means that when an update is made, it may take up to an hour for the change to propagate to other servers. For cases where this caching is problematic, use DeleteGeography, and then CreateGeography again, rather than UpdateGeography.

Names are limited to 50 characters and descriptions are limited to 500 characters. If they exceed those limits, they will be truncated.


Requests

Example UpdateGeography request
Query
http://{serverPath}.INRIX.com/traffic/Inrix.ashx?Action=UpdateGeography&GeoId=10207&Name=GeographySampleName2&Token={token}
Body
<Polygon xmlns="http://www.opengis.net/gml">
  <exterior>
    <LinearRing>
      <posList>
    47.65 -122.27 47.63 -122.27 47.63 -122.25 47.65 -122.25 47.65 -122.27
      </posList>
    </LinearRing>
  </exterior>
</Polygon>

Responses

200 Success
<Inrix docType="UpdateGeography" copyright="Copyright INRIX Inc." versionNumber="3.4.0" createdDate="2010-08-19T22:53:18Z" statusId="0" statusText="" responseId="400e4d41-2586-4862-a21f-812e977daf07" />
10 Error: Geography ID does not correspond to a geography that belongs to your vendor.
statusText: Geography not found
81 Error: No changes to update were included in the request.
statusText: No changes requested
980 (1) Error: Invalid GML. For example, not having an area greater than zero.
statusText: Invalid GML document.
980 (2) Error: Area of polygon is too large. Often this is due to defining the points in a clockwise direction, thereby accidentally defining the area outside the defined polygon.
statusText: GML exceeds size restrictions

/?Action=DeleteGeography

GET Deletes the specified geography.

Parameters

  = required
Name Located In Type Description
action Query String Use DeleteGeography
token Query String A valid authorization token returned in response to a GetSecurityToken request.
geoId Path Integer The ID of the geography to be deleted.

Notes

You can only delete a geography that belongs to your vendor.


Requests

Example DeleteGeography request
Query
http://{serverPath}.INRIX.com/traffic/Inrix.ashx?Action=DeleteGeography&GeoId=10006&Token={token}

Responses

200 Success
<Inrix docType="DeleteGeography" copyright="Copyright INRIX Inc." versionNumber="3.4.0" createdDate="2010-08-18T22:13:54Z" statusId="0" statusText="" responseId="14ff2cf2-67f0-4e39-b36f-aae04b01711c"/>
10 Error: Geography ID does not correspond to a geography that belongs to your vendor.
statusText: Geography not found