dataservices-api/doc/API.md

Geocoder API

Overview

WIP

Quickstart

WIP

General concepts

The Geocoder API offers geocoding services on top of the CartoDB SQL API by means of a set of geocoding functions. Each one of these functions is oriented to one kind of geocoding operation and it will return the corresponding geometry (a polygon or a point) according to the input information.

The Geocoder API decouples the geocoding service from the CartoDB Editor, and allows to geocode data (being single rows, complete datasets or simple inputs) programatically.

Errors

Errors will be described in the response of the geocoder request. An example is as follows:

{
   error: [
        "function geocode_countries(text) does not exist"
   ]
}

Due to the fact that the Geocoder API is used on top of the CartoDB SQL API you can check the Making calls to the SQL API section to help you debug your SQL errors.

Pre/post conditions

WIP

Possible side-effects

The Geocoder API can return different types of geometries as result of different geocoding processes. The CartoDB platform does not support multigeometry layers or datasets, therefore the final users of this Geocoder API must check that they are using consistent geometry types inside a table to avoid further conflicts in the map visualization.

====

For each function: function names function parameters and types return type for the functions (Geometry or NULL if not found, with SRID 4326)

Reference

WIP

Geocoding functions

WIP

Country geocoder function

This function provides a country geocoding service by receiving a country name text as parameter and returns a polygon geometry (projected in WGS 84 SRID 4326) for the corresponding country.

geocode_admin0_polygon

• geocode_admin0_polygon(country_name text)

  • Parameters: A text parameter with the name of the country to geocode.

  • Return type: polygon

  • Usage example:

    SELECT

    SELECT geocode_admin0_polygon('France')
    

    UPDATE

    UPDATE {tablename} SET {the_geom} = geocode_admin0_polygon({country_column})
    

Level-1 Administrative regions geocoder

geocode_admin1_polygon

• Functions:

  • geocode_admin1_polygon(admin1_name text)

    • Parameters:

    • Return type: polygon

    • Usage example:

      SELECT

      SELECT geocode_admin1_polygon('Alicante')
      

      UPDATE

      UPDATE {tablename} SET the_geom = geocode_admin1_polygon({province_column})
      

  • geocode_admin1_polygon(admin1_name text, country_name text)

  • Parameters:

  • Return type: polygon

  • Usage example:

  SELECT SELECT geocode_admin1_polygon('Alicante', 'Spain')

  UPDATE

  UPDATE {tablename} SET the_geom = geocode_admin1_polygon({province_column}, {country_column})
  

City geocoder

geocode_namedplace_point

• Functions:

  • geocode_namedplace_point(city_name text)

  • Parameters:

  • Return type: point

  • Usage example:

    SELECT

    SELECT geocode_namedplace_point('Barcelona')
    

    UPDATE

    UPDATE {tablename} SET the_geom = geocode_namedplace_point({city_column})
    

  • geocode_namedplace_point(city_name text, country_name text)

  • Parameters:

  • Return type: point

  • Usage example:

    SELECT

    SELECT geocode_namedplace_point('Barcelona', 'Spain')
    

    UPDATE

    UPDATE {tablename} SET the_geom = geocode_namedplace_point({city_column}, 'Spain')
    

  • geocode_namedplace_point(city_name text, admin1_name text, country_name text)

  • Parameters:

  • Return type: point

  • Usage example:

    SELECT geocode_namedplace_point('New York', 'New York', 'USA')
    

Postal codes geocoder

geocode_postalcode_polygon

• Functions:
  • geocode_postalcode_polygon(code text, country_name text)
    • Parameters:
    • Return type: polygon
    • Usage example:

      SELECT geocode_postalcode_polygon('11211', 'USA')
      

geocode_postalcode_point

• Functions:
  • geocode_postalcode_point(code text, country_name text)
    • Parameters:
    • Return type: point
    • Usage example:

      SELECT geocode_postalcode_point('11211', 'USA')
      

IP addresses Geocoder

geocode_ip_point

• Functions:
  • geocode_ip_point(ip_address text)
    • Parameters:
    • Return type: point
    • Usage example:

      SELECT geocode_ip_point('102.23.34.1')