Version: 1.0
Last Updated: 2023-10-10

Search API

The search API is a service that allows converting addresses into geographic coordinates, also known as forward geocoding, and geographic coordinates into an approximated address or place, also known as reverse geocoding.

Credits

Each successful request, i.e 200 status code, is equivalent to 1 credit.

Enpoint

GET https://api.geocody.com/1.0/search?key=YOUR-API-KEY&q=QUERY-TO-SEARCH

Here are some examples:

Address geocoding

curl --request GET \
     --url 'https://api.geocody.com/1.0/search?key=YOUR-API-KEY&q=1000%20Madison%20Drive%20NW%20,Washington,%20D.C.%2020560,%20US'

Coordinates geocoding

curl --request GET \
     --url 'https://api.geocody.com/1.0/search?key=YOUR-API-KEY&q=38.89021525192128,-77.02624573249005'

Coarse geocoding

curl --request GET \
     --url 'https://api.geocody.com/1.0/search?key=YOUR-API-KEY&q=Bogota,%20Colombia'

Query parameters

Field Type Optionality Description
key String Required Your API key. Sign Up for an API Key
q String Required The query string to search.
  • When searching for addresses this is a free form query string, you must include, and be limited to, the address and/or other information as the city, state and Country. Any additional address elements such as phone numbers, people names, or any other reference that doesn't represent an address or place should be avoided
  • When searching for coordinates you must include the latitude followed by a comma followed by the longitude, as shown in the example (38.89021525192128,-77.02624573249005)
IMPORTANT:The query string must be URL encoded, especially if it contains special characters or spaces.
qid String Optional An input ID that you define to identify the query.

Search Response

The search response is returned in a json format as describe here:

Response

Field Type Description
status Integer The status code of this response, for more information please refer to the HTTP Status Codes section is this document
message String A simple message describing the result of the request
results Result[] An array containig all the results found. This array might be empty when no result is found.

Result

Field Type Description
type String Describes the type of result found: address|place.
input_id String The same qid that you have defined in the query parameters
input String The same q that you have defined in the query parameters
score Double A decimal number between 0.0 and 1.0 that measure how accurate the result matches the input query. A higher score represents a better match
partial_match Boolean true when one or more elements in the input query were not identified otheriwse false
address Address Describes the address found. This might be null or not exits at all when the result is of type place
place Place Describes the place found. This might be null or not exits at all when the result is of type address
geocode Geocode The geocode generated for the input query
analysis Analysis Detailed information about the address and how well the resulting address matches the original query. This information might not be available for places
time_zone TimeZone The time zone associated to this result. This information might not be available for all results
extra - A set of extra properties associated to the result. These properties depends on the country to where the result belongs to, and might be empty or null for some countries

Address

Field Type Description
full_address String The whole address that can be used as a label to be displayed
components String A set of properties that describe an address and its components
components.admin1 String A admin1 level country sub-division. Represents the Country
components.admin2 String A admin2 level country sub-division. For most of the countries is a State, Province or Departament
components.admin3 String A admin3 level country sub-division. For most of the countries is a City, County or Municipality
components.admin4 String A admin4 level country sub-division. For most of the countries is a Locality or City
components.admin5 String A admin5 level country sub-division. For most of the countries is a borough or district
components.admin6 String A admin6 level country sub-division. For most of the countries is a neighbourhood
components.postcode String The postcode (zipcode) where available
components.admin1_short String A two letter short code for the admin1 level, ISO 3166 code of the country, for example co for Colombia
components.admin2_short String A short code for the admin 2 level, for example CA for California in the United States.
components.street String The street name
components.house_number String The house number, might include a prefix and/or suffix depending on the country
components.extra String Extra information about the address like unit number

Place

Field Type Description
name String The name of the place location
components String A set of properties that describe the place
components.admin1 String A admin1 level country sub-division. Represents the Country
components.admin2 String A admin2 level country sub-division. For most of the countries is a State, Province or Departament
components.admin3 String A admin3 level country sub-division. For most of the countries is a City, County or Municipality
components.admin4 String A admin4 level country sub-division. For most of the countries is a Locality or City
components.admin5 String A admin5 level country sub-division. For most of the countries is a borough or district
components.admin6 String A admin6 level country sub-division. For most of the countries is a neighbourhood
components.postcode String The postcode (zipcode) where available
components.admin1_short String A two letter short code for the admin1 level, ISO 3166 code of the country, for example co for Colombia
components.admin2_short String A short code for the admin 2 level, for example CA for California in the United States.

Geocode

Field Type Description
ok Boolean true if the result was geocoded false otheriwse
type String forward when the geocoded result came from a forward geocoding query, reverse when the input query were coordinates
accuracy String the accuracy of the geocode:
  • subpremise
  • nearest_house_number
  • house_number
  • rooftop
  • parcel_centroid
  • range_interpolation|range_interpolated
  • street_centroid
  • intersection
geometry GeoJson A geojson geometry, most of the times a Point, that represents the geographic coordinates (longitud, latitud) of the geocode
altitude Integer The altitude in meters of the geocoded point. This value could be null
bbox Double[] An array that represents a bounding box with the minLon, minLat, maxLon and maxLat of the geocode
geographic_coordinate_data_license Integer
  • 0 Results with this coordinate license are provided with the same license as the source data license
  • 1 Geocody grants you a limited, non-transferable, non-sublicensable, revocable license to use the geocoding data values for internal business use purposes only and for the duration of the term stated for the online subscription.

Analysis

Field Type Description
validation String no when the address has not been validated, non-postal when the address has been validated against a non postal address database, and postal when the address has been validated against a postal address database
status String The current address status verified|partial|ambiguous|plausible|nonvalid|none|unknown|expired|retired|not-an-address
address_precision String The location precisionundetermined|administrative_area|locality|thoroughfare|parcel|gatehouse|premise|subpremise
adi String Address Default Indicator. Indicates whether the address is the default address for a building; for example, the main lobby (true|false|unknown)
rdi String Residential Delivery Indicator, indicates when the address is residential (yes|no|plausible|unknown)
delivery_point String Indicates whether the address is a delivery point (true|false|plausible|unknown)
changes Change[] All changes that where made to try to match the inpunt query with an address
footnotes Footnote[] A list with footnotes codes describing annotations made to the address

Change

Field Type Description
from String Original query input sub string that changed. null when value was inferred
to String Output changed
type String Type of change (modified|removed|inferred)
footnote Footnote The footnote describing the change that was made
component String The address component that changed

Footnote

Code Definition Description
DS1 Fixed abbreviations The address was standardized. For example, if CALLE was in the delivery address, we will return CL as its standard spelling.
D01 Entire address is valid The address was found
D02 Address not found The address, exactly as submitted, could not be found or corrected. Either the primary number is missing, the street is missing, or the street is too badly misspelled to understand.
D03 Insufficient/Incorrect address data The submitted address did not contain sufficiently complete or correct data to be determined as valid address
D04 Ambiguous address The submitted address produces multiple valid address candidates
D05 Changed address component Some address components (i.e., directional or suffix) were added, changed, or deleted in order to achieve a match.
D06 Preferred address The address is matchable, but it is known by another (preferred) name
D07 Invalid delivery address The address was found, but it might not be a valid delivery point
D08 No longer exists The address was valid once, but it no longer exists
S01 Missing secondary number The address as submitted is missing a secondary number (apartment, suite, etc.)
S02 Unrecognized secondary number The secondary information (apartment, suite, etc.) was not recognized
S03 House Number not found The house number was not found, a nearest house number was returned
A01 Insufficient/Incorrect administrative data The submitted administrative data did not contain sufficiently complete or correct data or is missing
P01 Incorrect or missing Postcode The submitted postcode was not correct or was missing

TimeZone

Field Type Description
time_zone String The time zone id
utc_offset String The time zone offset, such as UTC-05:00
current_time String Outputs this date-time as a String, such as 2007-12-03T10:15:30+01:00[Europe/Paris]. The format consists of the Local Date Time followed by the Zone Offset. If the Zone Id is not the same as the offset, then the ID is output. The output is compatible with ISO-8601 if the offset and ID are the same, and the seconds in the offset are zero.
display_name String A long standard time name of this Time Zone suitable for presentation to the user.
display_name_short String A short standard time name of this Time Zone suitable for presentation to the user.
dts Integer The amount of time to be added to local standard time to get local wall clock time
use_daylight_time Boolean true if this TimeZone uses Daylight Saving Time
observes_daylight_time Boolean true if this TimeZone is currently in Daylight Saving Time, or if a transition from Standard Time to Daylight Saving Time occurs at any future time.
current_utc_offset String The current zone offset, such as UTC+01:00
current_utc_offset_total Integer The total zone offset in seconds

Extra

Field Type Country Description
coddane String CO 5 digit code (DIVIPOLA) for cities in Colombia
estrato String CO Estrato
upz String CO UPZ name for Bogotá addresses
postcode9 String CO Extended post code for Colombia
lupap_code String CO City code corresponding to lupap codes

Response example


{
  "status": 200,
  "message": "ok",
  "results": [{
      "type": "address",
      "input": "1000 Madison Drive NW Washington, D.C. 20560, US",
      "score": 0.9659620523452759,
      "input_id": null,
      "partial_match": false,
      "address": {
        "components": {
          "extra": null,
          "admin1": "United States",
          "admin2": "District Of Columbia",
          "admin3": "Washington",
          "admin4": null,
          "admin5": null,
          "admin6": null,
          "street": "Madison NW",
          "postcode": "20560",
          "admin1_short": "us",
          "admin2_short": "DC",
          "house_number": "1000"
        },
        "full_address": "1000 Madison NW, Washington, DC 20004, United States"
      },
      "place": null,
      "geocode": {
        "ok": true,
        "type": "forward",
        "accuracy": "rooftop",
        "altitude": null,
        "bbox": [
          -77.02634573249006,
          38.89011525192128,
          -77.02614573249005,
          38.89031525192129
        ],
        "geometry": {
          "type": "Point"
          "coordinates": [ -77.02624573249005, 38.89021525192128 ]
        },
        "attribution": "Data retrieved from Open Data DC catalog (https://opendata.dc.gov)",
        "geographic_coordinate_data_license": 0
      },
      "analysis": {
        "validation": "no",
        "status": "plausible",
        "address_precision": "premise",
        "adi": "unknown",
        "rdi": "unknown",
        "delivery_point": "unknown",
        "changes": [{
            "from": "Madison Drive NW",
            "to": "Madison NW",
            "type": "modified",
            "footnote": "D05",
            "component": "street"
        }],
        "footnotes": [ "D05" ]
      },
      "time_zone": {
        "time_zone": "America/New_York",
        "utc_offset": "UTC-05:00",
        "current_time": "2023-10-09T14:56:14.304272100-04:00[America/New_York]",
        "display_name": "Eastern Standard Time",
        "display_name_short": "EST",
        "dts": 3600,
        "use_daylight_time": true,
        "observes_daylight_time": true,
        "current_utc_offset": "UTC-04:00",
        "current_utc_offset_total": -14400
      },
      "extra": {
        
      }
    }
  ]
}

Search Coverage

Country Coverage Type
AR Limited to the city of CABA Line interpolation
AU Countrywide Parcel centroid, House numbers
BR Limited to: Sao Paulo, Belo Horizonte Parcel centroid
CA Limited to the province of QC Line interpolation
CL Countrywide Line interpolation
CO Countrywide For Colombian address please goto https://developer.lupap.com
FR Limited to the city of Paris House numbers
JM Countrywide Parcel centroid
MX Limited to the following cities:
   CDMX
   Monterrey, Guadalupe, Apodaca, San Nicolás de los Garza, Santa Catarina, San Pedro Garza García
   Guadalajara, Zapopan, Tlaquepaque, Tonalá
   Puebla
   Toluca
   Leon
   Nuevo Laredo
   Naucalpan de Juárez, Naucalpan, Ciudad López Mateos, Tlalnepantla de Baz 		House number
NZ Countrywide Parcel centroid, House numbers
US Countrywide Line interpolation limited to TIGER/Line data

Important: We are constantly updating our data quality and expanding our current coverage. Please let us know which country or area should we upload next info@geocody.com

Map Tiles API

The Map Tiles API is a service that allows rendering vector map tiles in pbf format, you can use tools like MapLibre, OpenLayers or any other library that allows to render vector map tiles.

Tiles follows the Open Map Tiles schema.

Tiles are based in OpenStreetMap data, so you must include the required attributions when displaying the map. Please refere to the following links:
https://osmfoundation.org/wiki/Licence/Attribution_Guidelines
https://openmaptiles.org/

Or just include the following attribution in your map:


<a href="https://geocody.com">Geocody</a> | <a href="https://openmaptiles.org/" rel="nofollow">&copy; OpenMapTiles</a> | <a href="https://www.openstreetmap.org/copyright" rel="nofollow">&copy; OpenStreetMap contributors</a>

Credits

Each successful request, i.e 200 status code, is equivalent to 0.1 credits.

Enpoint

GET https://api.geocody.com/1.0/tiles/{z}/{x}/{y}?key=YOUR-API-KEY

MapLibre Example

Using our basic style: 


let map = new maplibregl.Map({
    container: 'map',
    style: 'https://api.geocody.com/1.0/tiles/styles/basic.json?key=YOUR-API-KEY',
    center: [-74, 4], // starting position [lng, lat]
    zoom: 0 // starting zoom
});

With out style: 


let map = new maplibregl.Map({
    container: 'map',
    style: 'https://api.geocody.com/1.0/tiles/styles/basic.json?key=YOUR-API-KEY',
    center: [-74, 4], // starting position [lng, lat]
    zoom: 0 // starting zoom
});

HTTP Status Codes

The Geocody API uses the following status codes:

Status Meaning
200 Request was successful
404 Result not found: We didn't find any result to your query
401 Unauthorized: The credentials were provided incorrectly or did not match any existing, active credentials.
402 Payment Required: There are non available credits to process the request.
403 Forbidden: The access was forbidden, maybe an IP address or Http Referrer/Origin was not allowed.
500 Internal Server Error: An unknown error, please try again after some time or contact us at info@geocody.com