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:
- Applications that show traffic broken down by regions such as major metropolitan areas and counties.
- Applications that analyze traffic information such as incidents by specified regions.
- Applications with versions that are designed to only show traffic for a particular country.
The image below illustrates how traffic data is limited to the U.S. 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: 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.
Geography Functionality
Geographies can be used as input to specify regions with the following requests:
| API Name | Description |
|---|---|
| incident-api.inrix.com/v1/incidents?geoid= | Retrieves XD traffic-related incidents in a specified region. |
| segment-api.inrix.com/v1/segments/speed?geoid= | 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:
- Geographies may have no more than 10,000 vertices in their polygons.
- Geographies should not cross continents.
- Geography borders cannot cross over themselves.
- Geography borders cannot cross over themselves.
- Geographies should not cross the 180th meridian (180 degrees East or West of the Prime Meridian).
- Geographies must have an area greater than zero.
- Geographies cannot be larger than a hemisphere. It is acceptable for a geography to cross from the Eastern Hemisphere to the Western Hemisphere, or from South to North, but the smallest circle that can encompass your geometry cannot be greater than a half of the globe.
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 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. | ||||||
|
|||||||||
| 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. |
| outputfields | Path | String | If value of all is included, response includes the Type and Country elements. |
| country | Path | String | Filter geographies returned to only those with the specified 3 letter country code. |
| type | Path | String | Filter geographies returned to only those with the type. Types can include Country, State and Market. |
Notes
GetGeography is used for two purposes:
- 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.
- 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.
| GeoId | Description |
|---|---|
| 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
Queryhttp://{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. | |||||||||||||||||||||
|
|||||||||||||||||||||||
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. | ||||||
|
|||||||||
| 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
Queryhttp://{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 found81 Error: No changes to update were included in the request.
statusText: No changes requested980 (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
Queryhttp://{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