# Introducción
The Directions API is a service that calculates directions between locations using an HTTP request.
With the Directions API, you can:
- Search for directions for several modes of transportation, including transit, driving, walking or cycling.
- Return multi-part directions using a series of waypoints.
The API returns the most efficient routes when calculating directions. Travel time is the primary factor optimized, but the API may also take into account other factors such as distance and many more when deciding which route is the most efficient.
# Important
This document is intended for website and mobile developers who want to compute direction data within maps provided by one of the Google Maps APIs. It provides an introduction to using the API and reference material on the available parameters.
# Routing API Request Format
A Routing API request takes the following form:
https://apis.geodir.co/routing/v1/outputFormat?parameteres
where outputFormat may be either of the following values:
- json (recommended) indicates output in JavaScript Object Notation (JSON); or
- xml indicates output in XML
Security is important and HTTPS is recommended whenever possible, especially for applications that include sensitive user data, such as a user's location, in requests. Using HTTPS encryption makes your application more secure, and more resistant to snooping or tampering.
Note: URLs must be properly encoded (opens new window) (See best practices (opens new window)) to be valid and are limited to 8000 characters for all web services. Be aware of this limit when constructing your URLs. Note that different browsers, proxies, and servers may have different URL character limits as well.
Some parameters are required while some are optional. As is standard in URLs, parameters are separated using the ampersand (&) character.
# Request parameters
Certain parameters are required while others are optional. As is standard in URLs, all parameters are separated using the ampersand (&) character. All reserved characters (for example the plus sign "+") must be URL-encoded. The list of parameters and their possible values are enumerated below.
# Required parameters
- origin — Textual latitude/longitude value from which you wish to calculate directions.
origin=12.065772,-77.054688
- destination — Textual latitude/longitude value to which you wish to calculate directions. The options for the destination parameter are the same as for the origin parameter, described above.
destination=12.069963,-77.055155
- key: Your application's API key. This key identifies your application for purposes of quota management. Learn how to obtain your API key.
# Optional parameters
- waypoints — Specifies an array of intermediate locations to include along the route between the origin and destination points as pass through or stopover locations. Waypoints alter a route by directing it through the specified location(s). The API supports waypoints for these travel modes: driving, walking and bicycling; not transit. You can specify waypoints using the following values:
- Latitude/longitude coordinates (lat/lng): an explicit value pair. (-34.92788%2C138.60008 comma, no space)
- language — The language in which to return results.
# Example Routing requests
The following request returns routing from coordinates 12.065772,-77.054688 to 12.069963,-77.055155
https://apis.geodir.co`[/routing/v1/json?origin=-12.065772,-77.054688&destination=-12.069963,-77.055155&key=YOUR_KEY](http://localhost:8072/routing/v1/json?origin=-12.065772,-77.054688&key=be32a644-f0c6-4a30-a4ea-4d03f7ba95bd&destination=-12.069963,-77.055155&waypoints=-12.067294,-77.054544&language=abc)
# Travel modes
When you calculate directions, you may specify the transportation mode to use. By default, directions are calculated as driving directions. The following travel modes are supported:
- car(default) indicates standard driving directions using the road network.
- pedestrian requests walking directions via pedestrian paths & sidewalks (where available).
- bicycle requests bicycling directions via bicycle paths & preferred streets (where available).
- transit requests directions via public transit routes (where available). If you set the mode to transit, you can optionally specify either a departure_time or an arrival_time. If neither time is specified, the departure_time defaults to now (that is, the departure time defaults to the current time). You can also optionally include a transit_mode and/or a transit_routing_preference.
Note: Both walking and bicycling directions may sometimes not include clear pedestrian or bicycling paths, so these directions will return warnings in the returned result which you must display to the user.
# Waypoints
Caution: Requests using more than 10 waypoints (between 11 and 25), or waypoint optimization, are billed at a higher rate
When calculating routes using the Routing API, you may specify waypoints to return a route that includes pass throughs or stopovers at intermediate locations.
You can supply one or more locations separated by the pipe character (| or %7C), in the form of a place ID, an address, or latitude/longitude coordinates. By default, the Routing service calculates a route using the waypoints in the order they are given.
- If you pass latitude/longitude coordinates, the values go directly to the front-end server to calculate directions without geocoding. The points are snapped to roads and might not provide the accuracy your app needs. Use coordinates when you are confident the values truly specify the points your app needs for routing without regard to possible access points or additional geocoding details. Ensure that a comma (%2C) and not a space (%20) separates the latitude and longitude values.
https://apis.geodir.co`[/routing/v1/json?origin=-12.065772,-77.054688&destination=-12.069963,-77.055155&waypoints=-12.067294,-77.054544&key=](http://localhost:8072/routing/v1/json?origin=-12.065772,-77.054688&destination=-12.069963,-77.055155&waypoints=-12.067294,-77.054544&key=be32a644-f0c6-4a30-a4ea-4d03f7ba95bd)YOUR_KEY
# Routing Responses
Routing responses are returned in the format indicated by the output flag within the URL request's path.
Sample HTTP request:
https://apis.geodir.co`[/routing/v1/json?origin=-12.065772,-77.054688&destination=-12.069963,-77.055155&waypoints=-12.067294,-77.054544&key=](http://localhost:8072/routing/v1/json?origin=-12.065772,-77.054688&key=be32a644-f0c6-4a30-a4ea-4d03f7ba95bd&destination=-12.069963,-77.055155&waypoints=-12.067294,-77.054544&language=abc)YOUR_KEY
{
"waypoints": [
{
"status": "OK",
"place_id": "23ab883e0b194dfc5c7a4839e4065f039e",
"result_types": [
"address"
]
},
{
"status": "OK",
"place_id": "f91650d6a6f5cab9e4e7724bb3904dc63e",
"result_types": [
"address"
]
},
{
"status": "OK",
"place_id": "bb27f1b281f2fcca9a90b914a56ecfda81",
"result_types": [
"address"
]
}
],
"routes": [
{
"copyrights": "Geodir and its suppliers ©2020",
"sections": [
{
"distance": 196,
"duration": 56,
"arrival_address": "Calle Copacabana 102, Pueblo Libre, Lima, Perú",
"arrival_coordinates": {
"lat": -12.0699467,
"lon": -77.0551862
},
"departure_address": "Jirón Pedro Ruiz Gallo 676, Breña, Lima, Perú",
"departure_coordinates": {
"lat": -12.0657787,
"lon": -77.0547019
},
"actions": [
{
"distance": 82,
"duration": 27,
"instruction": "Head <b>southeast</b> on <b>Jr. Pedro Ruiz Gallo</b>",
"polyline": "`rshAvvhuMZYd@_@NINGTI",
"arrival_coordinates": {
"lat": -12.0663699,
"lon": -77.05425129999999
},
"departure_coordinates": {
"lat": -12.0657667,
"lon": -77.0546822
},
"transport_mode": "car"
},
{
"distance": 114,
"duration": 29,
"instruction": "At the roundabout, take the <b>2nd</b> exit onto <b>Av. del Rio</b><div style=\"font-size:0.9em\">Destination will be on the left</div>",
"polyline": "xushA`thuM?@@@?@@@@@@@?@@@@@@@@?@@B?@@@?@?B?@?@?@?@?BA@?@A@??A@?FB?@@?@@^FpAZD@",
"arrival_coordinates": {
"lat": -12.0672897,
"lon": -77.0545691
},
"departure_coordinates": {
"lat": -12.0663699,
"lon": -77.05425129999999
},
"transport_mode": "car"
}
]
},
{
"distance": 499,
"duration": 172,
"arrival_address": "Calle Copacabana 102, Pueblo Libre, Lima, Perú",
"arrival_coordinates": {
"lat": -12.0699467,
"lon": -77.0551862
},
"departure_address": "Jirón Pedro Ruiz Gallo 676, Breña, Lima, Perú",
"departure_coordinates": {
"lat": -12.0657787,
"lon": -77.0547019
},
"actions": [
{
"distance": 199,
"duration": 37,
"instruction": "Head <b>south</b> on <b>Av. del Rio</b> toward <b>Rio Grande</b>",
"polyline": "p{shA`vhuMpALTBvAN^N|BT",
"arrival_coordinates": {
"lat": -12.0690375,
"lon": -77.0549262
},
"departure_coordinates": {
"lat": -12.0672897,
"lon": -77.0545691
},
"transport_mode": "car"
},
{
"distance": 123,
"duration": 22,
"instruction": "Turn <b>right</b> onto <b>Jirón J. J. Pasos</b>",
"polyline": "nfthAhxhuMTbBRvB",
"arrival_coordinates": {
"lat": -12.0692517,
"lon": -77.05603289999999
},
"departure_coordinates": {
"lat": -12.0690375,
"lon": -77.0549262
},
"transport_mode": "car"
},
{
"distance": 100,
"duration": 70,
"instruction": "Turn <b>left</b> onto <b>Teruel</b>",
"polyline": "xgthAd_iuMxAOtAU",
"arrival_coordinates": {
"lat": -12.0701324,
"lon": -77.0558381
},
"departure_coordinates": {
"lat": -12.0692517,
"lon": -77.05603289999999
},
"transport_mode": "car"
},
{
"distance": 77,
"duration": 43,
"instruction": "Turn <b>left</b> onto <b>Copacabana</b><div style=\"font-size:0.9em\">Destination will be on the left</div>",
"polyline": "hmthA~}huM[iC",
"arrival_coordinates": {
"lat": -12.0699867,
"lon": -77.05514980000001
},
"departure_coordinates": {
"lat": -12.0701324,
"lon": -77.0558381
},
"transport_mode": "car"
}
]
}
],
"polyline": "`rshAvvhuM`Ay@^QTG@BDFFDRBLE@?HDxBf@fBPvAN^N|BTTbBRvBxAOtAU[iC"
}
]
}
# Routings response elements
Note that the JSON response contains two root elements:
- waypoints contains an array with details about the geocoding of origin, destination and waypoints.
- routes contains an array of routes from the origin to the destination. See Routes below. Routes consist of nested sections and actions.
- copyrights contains the copyrights text to be displayed for this route. You must handle and display this information yourself.
- sections[] contains an array which contains information about a section of the route, between two locations within the given route. A separate section will be present for each waypoint or destination specified. (A route with no waypoints will contain exactly one leg within the sections array.) Each section consists of a series of actions.
- distance
- duration
- polyline contains a single points object that holds an encoded polyline representation of the route. This polyline is an approximate (smoothed) path of the resulting directions.
- arrival_address
- arrival_coordinates
- departure_address
- departure_coordinates
- actions[] contains an array of steps denoting information about each separate step of the section of the journey.
- distance indicates the total distance covered by this action.
- duration indicates the total duration of this action.
- instruccion
- polyline contains a single points object that holds an encoded polyline representation of the route. This polyline is an approximate (smoothed) path of the resulting directions.
- arrival_address
- arrival_coordinates
- departure_address
- departure_coordinates
# Status Codes
The "status" field within the Geocoding response object contains the status of the request, and may contain debugging information to help you track down why geocoding is not working. The "status" field may contain the following values:
- "OK" indicates that no errors occurred; the address was successfully parsed and at least one geocode was returned.
- "ZERO_RESULTS" indicates that the geocode was successful but returned no results. This may occur if the geocoder was passed a non-existent address.
- "OVER_QUERY_LIMIT" indicates that you are over your quota.
- "REQUEST_DENIED" indicates that your request was denied.
- "INVALID_REQUEST" generally indicates that the query.
- "UNKNOWN_ERROR" indicates that the request could not be processed due to a server error. The request may succeed if you try again.
# F-Results
When the geocoder returns results, it places them within a (JSON) results array. Even if the geocoder returns no results (such as if the address doesn't exist) it still returns an empty results array. (XML responses consist of zero or more result elements.)
A typical result contains the following fields:
result_types[] array indicates the type of the returned result. This array contains a set of zero or more tags identifying the type of feature returned in the result. For example, a geocode of "Breña" returns "locality" which indicates that "Breña" is a city, and also returns "political" which indicates it is a political entity.
standard_address is a string containing the human-readable address of this location.
Often this address is equivalent to the postal address.
The address standard is logically composed of one or more address segments. For example, the address "Jr Pedro Ruiz Gallo 668, Breña, Lima, PE" consists of the following components: "668" (the street number), "Jr Pedro Ruiz Gallo" (the route), "Breña" (the city) and "PE" (the country).
Do not parse the address standard programmatically. Instead you should use the individual address segments, which the API response includes in addition to the address standard field.
address_segments[] is an array containing the separate segments applicable to this address.
Each address segment typically contains the following fields:
types[] is an array indicating the of the address segments. See the list of supported types.
long_name is the full text description or name of the address component as returned by the Geocoder.
short_name is an abbreviated textual name for the address component, if available. For example, an address segment for the country of Peru may have a long_name of "Peru" and a short_name of "PE" using the 2-letter abbreviation.
Note the following facts about the address_segments[] array:
- The array of address segments may contain more segments than the address_standar
- The array does not necessarily include all the political entities that contain an address, apart from those included in the address_standard. To retrieve all the political entities that contain a specific address, you should use reverse geocoding, passing the latitude/longitude of the address as a parameter to the request.
- The format of the response is not guaranteed to remain the same between requests. In particular, the number of address_segments varies based on the address requested and can change over time for the same address. A component can change position in the array. The type of the segment can change. A particular segment may be missing in a later response.
To handle the array of segments, you should parse the response and select appropriate values via expressions. See the guide to parsing a response.
geometry contains the following information:
- coordinates contains the geocoded latitude, longitude value. For normal address lookups, this field is typically the most important.
- geocoding_type stores additional data about the specified location. The following values are currently supported:
- "DOOR" indicates that the returned result is a precise geocode for which we have location information accurate down to door precision.
- "INTERPOLATED" indicates that the returned result reflects an approximation (usually on a road) interpolated between two precise points (such as intersections). Interpolated results are generally returned when level DOOR are unavailable for address.
- "CENTER" indicates that the returned result is the geometric center of a result such as a polyline (for example, a street) or polygon (region).
- "NEAR" indicates that the returned result is approximate. For more details review Geocoding Types and Subtypes
- bbox contains the recommended viewport for displaying the returned result, specified as two latitude,longitude values defining the southwest and northeast corner of the bounding box.
place_id is a unique identifier that can be used with other Geodir APIs. For example, you can use the place_id in a Place API request to get details of a local business, such as phone number, opening hours, and more. See the place ID.
# Address Types and Segments
The types[] array in the result indicates the address type. Examples of address types include a street address, a country, or a political entity. There is also a types[] array in the address_segments[], indicating the type of each part of the address. Examples include street number or country. (Below is a full list of types.) Addresses may have multiple types. The types may be considered 'tags'. For example, many cities are tagged with the political and the locality type.
The following types are supported and returned by the geocoder in both the address type and address component type arrays:
- route indicates a named route (such as "Av Arequipa").
- crossing indicates a major intersection, usually of two major roads.
- political indicates a political entity. Usually, this type indicates a polygon of some civil administration.
- country indicates the national political entity, and is typically the highest order type returned by the Geocoder.
- admin_level_1 indicates a first-order civil entity below the country level. Within the Peru, these administrative levels are departamentos. Not all nations exhibit these administrative levels. In most cases, admin_level_1 short names will closely match ISO 3166-2 subdivisions and other widely circulated lists; however this is not guaranteed as our geocoding results are based on a variety of signals and location data.
- admin_level_2 indicates a second-order civil entity below the country level. Within the Peru, these administrative levels are provincias. Not all nations exhibit these administrative levels.
- admin_level_3 indicates a third-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.
- admin_level_4 indicates a fourth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.
- admin_level_5 indicates a fifth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.
- common_area indicates a commonly-used alternative name for the entity.
- locality indicates an incorporated city or town political entity. Within the Peru, these localities are distritos.
- locality_id indicates an incorporated code by city or town political entity. Within the Peru, these locality_id are ubigeo, for example 150105 for "Breña".
- sublocality indicates a first-order civil entity below a locality. For some locations may receive one of the additional types: sublocality_level_1 to sublocality_level_5. Each sublocality level is a civil entity. Larger numbers indicate a smaller geographic area. Within the Peru, these sublocality are nucleo urbano (urbanización), for example "Urb San Gregorio".
- neighborhood indicates a named neighborhood.
- premise indicates a named location, usually a building or collection of buildings with a common name. Within the Peru, these premise are condominio, for example "Res San Felipe".
- subpremise indicates a first-order entity below a named location, usually a singular building within a collection of buildings with a common name
- postal_code indicates a postal code as used to address postal mail within the country.
- natural_feature indicates a prominent natural feature.
- airport indicates an airport.
- park indicates a named park.
- poi indicates a named point of interest. Typically, these "POI"s are prominent local entities that don't easily fit in another category, such as "Plaza Norte" or "Macchupicchu".
An empty list of types indicates there are no known types for the particular address segment, for example, Macchupicchu in Peru.
In addition to the above, address segments may include the types below.
- floor indicates the floor of a building address.
- establishment typically indicates a place that has not yet been categorized.
- poi indicates a named point of interest.
- parking indicates a parking lot or parking structure.
- post_box indicates a specific postal box.
- postal_town indicates a grouping of geographic areas, such as locality and sublocality, used for mailing addresses in some countries.
- room indicates the room of a building address.
- route_number indicates the precise street number.
- bus_station, train_station and transit_station indicate the location of a bus, train or public transit stop.
# Region
In a Geocoding request, you can instruct the Geocoding service to return results biased to a particular region by using the region parameter. This parameter takes a ccTLD (opens new window) (country code top-level domain) argument specifying the region.
For example, A Geocoding request for "Miraflores" without region will return the Peruvian city.
A Geocoding request for "Miraflores" with region=bo (Bolivia) will return the Bolivian city.
# Segments Filtering
In a Geocoding response, the Geocoding API can return address results restricted to a specific area. You can specify the restriction using the segments filter. A filter consists of a list of segment:value pairs separated by a pipe (|). Filter values support the same methods of spelling correction and partial matching as other Geocoding requests.
The segments that can be filtered include:
- postal_code matches postal_code and postal_code_prefix.
- country matches a country name or a two letter ISO 3166-1 (opens new window) country code. The API follows the ISO standard for defining countries, and the filtering works best when using the corresponding ISO code of the country.
The following segments may be used to influence results, but will not be enforced:
- route matches the long or short name of a route.
- locality matches against locality and sublocality types.
- admin area matches all the admin area levels.
Notes about component filtering:
- If the request contains multiple component filters, the API evaluates them as an AND, not an OR. For example, if the request includes multiple countries segments=country:PE|country:BO, the API looks for locations where country=PE AND country=BO, and returns ZERO_RESULTS.
- Results are consistent with Geodir Maps, which occasionally yields unexpected ZERO_RESULTS responses. Using Placeli Autocomplete may provide better results in some use cases.
- For each address component, either specify it in the address parameter or in a components filter, but not both. Specifying the same values in both may result in ZERO_RESULTS.
A geocode for "Av Arequipa" with segments=locality_id:150116 returns a result in Lince, Perú rather than in Miraflores, Peru. Request:
https://apis.geodir.co/geocoding/v1/json?address=Av Arequipa&segments=locality_id:150116&key=YOUR_KEY