# What is Geocoding?

Geocoding is the process of converting addresses (like "Jr Pedro Ruiz 668, Breña, Lima, PE") into geographic coordinates (like latitude -12.065819 and longitude -77.054538), which you can use to place markers on a map, or position the map.

Reverse geocoding is the process of converting geographic coordinates into a human-readable address.

The Geocoding API provides a direct way to access these services via an HTTP request.

# Important

This document describes the Geocoding API web service. It is intended for website and mobile developers who want to use geocoding data within maps provided by one of the Geodir Platform APIs.

Note: This service is generally designed for geocoding static (known in advance) addresses for placement of application content on a map; this service is not designed to respond in real time to user input.

Before you start developing with the Geocoding API, review the authentication requirements (you need an API key) and the API pricing information.

# Geocoding API Request Format

A Geocoding API request takes the following form:

https://apis.geodir.co/geocoding/v1/outputFormat?parameters

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 (See best practices) 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.

# Geocoding (Latitude/Longitude Search)

Required parameters in a geocoding request:

address: Specify addresses in accordance with the format used by the national postal service of the country concerned. Additional address elements such as business names and unit, suite or floor numbers should be avoided. Street address elements should be delimited by spaces (shown here as url-escaped to %20):
```
address=Jiron%20Pedro%20Ruiz%20Gallo%20668
```

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 in a geocoding request:

segments: is a filter with elements separated by a pipe (|). The segments filter is also accepted as an optional parameter if an address is provided. Each element consists of a segment:value pair, and fully restricts the results from the geocoder. See more information about segments filtering.

# Geocoding Responses

Geocoding responses are returned in the format indicated by the output flag within the URL request's path.

In this example, the Geocoding API requests a json response for a query on "Jr Pedro Ruiz Gallo 668, Breña, Lima, PE".

This request demonstrates using the JSON output flag:

https://apis.geodir.co/geocoding/v1/json?address=jr pedro ruiz gallo nro 668&segments=locality_id:150105&key=YOUR_KEY

See below the sample JSON responses.

{
    "status": "OK",
    "results": [
        {
            "result_types": [
                "address"
            ],
            "address_segments": [
                {
                    "name": "668",
                    "name_abbr": "668",
                    "types": [
                        "route_number"
                    ]
                },
                {
                    "name": "Pedro Ruiz Gallo",
                    "name_abbr": "Pedro Ruiz Gallo",
                    "types": [
                        "route"
                    ]
                },
                {
                    "name": "Jirón",
                    "name_abbr": "Jr",
                    "types": [
                        "route_type"
                    ]
                },
                {
                    "name": "Lima",
                    "name_abbr": "Lima",
                    "types": [
                        "admin_level_1",
                        "political"
                    ]
                },
                {
                    "name": "15",
                    "name_abbr": "15",
                    "types": [
                        "admin_level_1_code",
                        "political"
                    ]
                },
                {
                    "name": "Lima",
                    "name_abbr": "Lima",
                    "types": [
                        "admin_level_2",
                        "political"
                    ]
                },
                {
                    "name": "1501",
                    "name_abbr": "1501",
                    "types": [
                        "admin_level_2_code",
                        "political"
                    ]
                },
                {
                    "name": "Breña",
                    "name_abbr": "Breña",
                    "types": [
                        "admin_level_3",
                        "political"
                    ]
                },
                {
                    "name": "150105",
                    "name_abbr": "150105",
                    "types": [
                        "admin_level_3_code",
                        "political"
                    ]
                },
                {
                    "name": "San Gregorio",
                    "name_abbr": "San Gregorio",
                    "types": [
                        "sublocality",
                        "political"
                    ]
                },
                {
                    "name": "Perú",
                    "name_abbr": "PE",
                    "types": [
                        "country",
                        "political"
                    ]
                },
                {
                    "name": "15083",
                    "name_abbr": "15083",
                    "types": [
                        "postal_code"
                    ]
                }
            ],
            "geometry": {
                "coordinates": {
                    "lat": -12.0658283,
                    "lon": -77.0546503
                },
                "bbox": [
                    -77.0546503,
                    -12.0658283,
                    -77.0546503,
                    -12.0658283
                ],
                "geocoding_type": "INTERPOLATED"
            },
            "place_id": "407779ce754bbb738c285742a8528fea55",
            "standard_address": "Jirón Pedro Ruiz Gallo 668, Breña, Lima, Perú"
        }
    ]
}

Note that the JSON response contains two root elements:

"status" contains metadata on the request. See Status Codes below.
"results" contains an array of geocoded address information and geometry information.

Generally, only one entry in the "results" array is returned for address lookups,though the geocoder may return several results when address queries are ambiguous.

Note that these results generally need to be parsed if you wish to extract values from the results. Parsing JSON is relatively easy. See Parsing JSON for some recommended design patterns.

# 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_DAILY_LIMIT indicates any of the following:
- The API key is missing or invalid.
- Billing has not been enabled on your account.
- A blank-imposed usage cap has been exceeded.
- The provided method of payment is no longer valid (for example, a credit card has expired).
"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 (address, segments or latlng) is missing.
"UNKNOWN_ERROR" indicates that the request could not be processed due to a server error. The request may succeed if you try again.

# 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.
- name is the full text description or name of the address component as returned by the Geocoder.
- name_abbr is an abbreviated textual name for the address component, if available. For example, an address segment for the country of Peru may have a name of "Peru" and a name_abbr 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_standard
- 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).
  - "APROXIMATE" 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.

# 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 following segments may be used to influence results, but will not be enforced:

locality matches against locality and sublocality types.

Notes about component filtering:

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

Reverse Geocoding →