### Performance Profiling

Source: https://datosgobar.github.io/georef-ar-api/georef-api-development

Starts the API server with cProfile enabled to generate performance metrics in the profile/ directory.

```bash
make start_profile_server
```

--------------------------------

### Configure systemd service for Georef API

Source: https://datosgobar.github.io/georef-ar-api/deploy

This snippet shows how to manage the Georef API as a systemd service. It includes commands to reload the systemd daemon, enable the service to start on boot, and start the service. It also demonstrates how to check the API's status and view logs.

```bash
sudo systemctl daemon-reload
sudo systemctl enable georef-ar-api
sudo systemctl start georef-ar-api

# To check if the API is running:
curl localhost:5000/api/provincias

# To view logs:
sudo journalctl -u georef-ar-api
```

--------------------------------

### GET /direcciones

Source: https://datosgobar.github.io/georef-ar-api/open-api

Normalizes a specific geographic address.

```APIDOC
## GET /direcciones

### Description
Normalizes a provided address string into standardized geographic components.

### Method
GET

### Endpoint
https://apis.datos.gob.ar/georef/api/direcciones

### Parameters
#### Query Parameters
- **direccion** (string) - Required - The address string to normalize.

### Response
#### Success Response (200)
- **direcciones** (array) - List of normalized address results.

#### Response Example
{
  "direcciones": [
    { "calle": { "nombre": "Av. Corrientes" }, "altura": 1000 }
  ]
}
```

--------------------------------

### GET /asentamientos

Source: https://datosgobar.github.io/georef-ar-api/localities

Retrieves a list of human settlements from the BAHRA dataset, covering a broader range of geographical entities.

```APIDOC
## GET /asentamientos

### Description
Returns the full list of human settlements from BAHRA, including locations that may not be classified as standard localities.

### Method
GET

### Endpoint
/asentamientos

### Parameters
#### Query Parameters
- **nombre** (string) - Optional - Filter by settlement name

### Request Example
GET /asentamientos?nombre=Paraje+X

### Response
#### Success Response (200)
- **asentamientos** (array) - List of settlement objects

#### Response Example
{
  "asentamientos": [
    {
      "id": "99999999999",
      "nombre": "Paraje X"
    }
  ]
}
```

--------------------------------

### GET /provincias

Source: https://datosgobar.github.io/georef-ar-api/open-api

Retrieves a list of provinces in Argentina.

```APIDOC
## GET /provincias

### Description
Returns a list of all provinces available in the database.

### Method
GET

### Endpoint
https://apis.datos.gob.ar/georef/api/provincias

### Response
#### Success Response (200)
- **provincias** (array) - List of province objects containing id and name.

#### Response Example
{
  "provincias": [
    { "id": "02", "nombre": "Ciudad Autónoma de Buenos Aires" },
    { "id": "06", "nombre": "Buenos Aires" }
  ]
}
```

--------------------------------

### GET /direcciones

Source: https://datosgobar.github.io/georef-ar-api/history

Geolocates street addresses and returns coordinate information.

```APIDOC
## GET /direcciones

### Description
Geolocates a specific street address. The API parses the input string to extract street name and house number.

### Method
GET

### Endpoint
/direcciones

### Parameters
#### Query Parameters
- **direccion** (string) - Required - The address string to geolocate.
- **orden** (string) - Optional - Sort order for results.
- **inicio** (integer) - Optional - Pagination offset.

### Request Example
GET /direcciones?direccion=Corrientes+1000

### Response
#### Success Response (200)
- **direcciones** (array) - List of geolocated addresses.
- **inicio** (integer) - Current pagination offset.

#### Response Example
{
  "direcciones": [
    { "calle": { "nombre": "Corrientes" }, "altura": 1000 }
  ]
}
```

--------------------------------

### GET /ubicacion

Source: https://datosgobar.github.io/georef-ar-api/open-api

Performs reverse geocoding for a given coordinate point.

```APIDOC
## GET /ubicacion

### Description
Performs reverse geocoding to find geographic entities associated with a specific latitude and longitude.

### Method
GET

### Endpoint
https://apis.datos.gob.ar/georef/api/ubicacion

### Parameters
#### Query Parameters
- **lat** (float) - Required - Latitude coordinate.
- **lon** (float) - Required - Longitude coordinate.

### Response
#### Success Response (200)
- **ubicacion** (object) - Geographic details for the provided coordinates.

#### Response Example
{
  "ubicacion": { "provincia": "Buenos Aires", "departamento": "La Matanza" }
}
```

--------------------------------

### GET /localidades

Source: https://datosgobar.github.io/georef-ar-api/localities

Retrieves a list of localities based on the BAHRA dataset, representing areas with continuous built-up surfaces.

```APIDOC
## GET /localidades

### Description
Returns a subset of BAHRA data representing localities, which are areas characterized by continuous built and unbuilt surfaces connected by streets.

### Method
GET

### Endpoint
/localidades

### Parameters
#### Query Parameters
- **nombre** (string) - Optional - Filter by locality name

### Request Example
GET /localidades?nombre=Cordoba

### Response
#### Success Response (200)
- **localidades** (array) - List of locality objects

#### Response Example
{
  "localidades": [
    {
      "id": "14014010001",
      "nombre": "Córdoba"
    }
  ]
}
```

--------------------------------

### GET /provincias

Source: https://datosgobar.github.io/georef-ar-api/history

Retrieves a list of provinces in Argentina with support for geometric intersections and various output formats.

```APIDOC
## GET /provincias

### Description
Retrieves geographic data for provinces. Supports filtering by intersection with other entities and exporting in multiple formats.

### Method
GET

### Endpoint
/provincias.{format}

### Parameters
#### Query Parameters
- **campos** (string) - Optional - Specify fields to return (e.g., 'basico', 'estandar', 'completo', or specific field prefixes).
- **interseccion** (string) - Optional - Filter by intersection with other entities (e.g., municipalities, departments).
- **aplanar** (boolean) - Optional - Flatten nested objects in the response.

### Request Example
GET /provincias.json?campos=basico

### Response
#### Success Response (200)
- **provincias** (array) - List of province objects.
- **cantidad** (integer) - Number of results returned.
- **total** (integer) - Total number of results available.

#### Response Example
{
  "cantidad": 24,
  "total": 24,
  "provincias": [
    { "id": "02", "nombre": "Ciudad Autónoma de Buenos Aires" }
  ]
}
```

--------------------------------

### GET /direcciones

Source: https://datosgobar.github.io/georef-ar-api/history

Endpoint to normalize and geocode addresses. It interprets input strings and returns standardized street and intersection data.

```APIDOC
## GET /direcciones

### Description
Normalizes and geocodes a provided address string, returning detailed information about the street, intersections, and location.

### Method
GET

### Endpoint
/direcciones

### Parameters
#### Query Parameters
- **direccion** (string) - Required - The address string to normalize.
- **formato** (string) - Optional - Response format (xml, json).

### Response
#### Success Response (200)
- **calle** (object) - Normalized street object containing name, id, and category.
- **altura** (object) - Contains value and unit of the address number.
- **piso** (string) - Floor information if provided.

### Response Example
{
  "calle": { "nombre": "Avenida Santa Fe", "id": "123", "categoria": "calle" },
  "altura": { "valor": 100, "unidad": "m" }
}
```

--------------------------------

### Search Provinces

Source: https://datosgobar.github.io/georef-ar-api/quick-start

This endpoint allows you to search for provinces by name.

```APIDOC
## GET /provincias

### Description
Searches for provinces based on the provided name.

### Method
GET

### Endpoint
`https://apis.datos.gob.ar/georef/api/provincias`

### Query Parameters
- **nombre** (string) - Required - The name of the province to search for.

### Response
#### Success Response (200)
- **provincias** (array) - A list of matching provinces.
  - **id** (string) - The province ID.
  - **centroide** (object) - The centroid coordinates of the province.
    - **lat** (number) - Latitude.
    - **lon** (number) - Longitude.
  - **nombre** (string) - The name of the province.
- **cantidad** (integer) - The number of provinces returned.
- **total** (integer) - The total number of matching provinces.
- **inicio** (integer) - The starting index of the results.
- **parametros** (object) - The parameters used for the query.

### Response Example
```json
{
    "provincias": [
        {
            "id": "14",
            "centroide": {
                "lat": -32.142933,
                "lon": -63.801753
            },
            "nombre": "CÓRDOBA"
        }
    ],
    "cantidad": 1,
    "total": 1,
    "inicio": 0,
    "parametros": { ... }
}
```
```

--------------------------------

### Enable and Validate Nginx configuration for Georef API

Source: https://datosgobar.github.io/georef-ar-api/deploy

This snippet outlines the process of enabling a new Nginx site configuration and validating the overall Nginx configuration. It includes creating a symbolic link to activate the site and a command to test the configuration syntax before restarting the Nginx service.

```bash
sudo ln -s /etc/nginx/sites-available/georef-ar-api.nginx /etc/nginx/sites-enabled/georef-ar-api.nginx

# Validate Nginx configuration:
sudo nginx -T

# Restart Nginx to apply changes:
sudo systemctl restart nginx.service

# Check API status after Nginx restart:
curl localhost/api/provincias
```

--------------------------------

### Ejemplo de Petición GET para Normalizar Dirección con Parámetros

Source: https://datosgobar.github.io/georef-ar-api/addresses

Este ejemplo muestra cómo realizar una petición GET a la API Georef-AR para normalizar una dirección específica. Incluye parámetros como 'direccion', 'departamento' y 'provincia' para obtener resultados más precisos. La librería georef-ar-address se utiliza internamente para interpretar la estructura de la dirección.

```HTTP
GET https://apis.datos.gob.ar/georef/api/direcciones?direccion=Av. Santa Fe nro 260 2ndo C, entre Santa Rosa y Colón&departamento=capital&provincia=cordoba
```

--------------------------------

### Search Municipalities

Source: https://datosgobar.github.io/georef-ar-api/quick-start

This endpoint allows you to search for municipalities within a specific province, with an option to flatten the results.

```APIDOC
## GET /municipios

### Description
Searches for municipalities within a specified province. The `aplanar` parameter can be used to simplify the response structure.

### Method
GET

### Endpoint
`https://apis.datos.gob.ar/georef/api/municipios`

### Query Parameters
- **provincia** (string) - Required - The name of the province to search within.
- **aplanar** (boolean) - Optional - If true, flattens the municipality object in the response.

### Response
#### Success Response (200)
- **municipios** (array) - A list of matching municipalities.
  - **centroide_lat** (number) - Latitude of the municipality's centroid.
  - **centroide_lon** (number) - Longitude of the municipality's centroid.
  - **id** (string) - The municipality ID.
  - **nombre** (string) - The name of the municipality.
  - **provincia_id** (string) - The ID of the province the municipality belongs to.
  - **provincia_nombre** (string) - The name of the province.
- **cantidad** (integer) - The number of municipalities returned.
- **total** (integer) - The total number of matching municipalities.
- **inicio** (integer) - The starting index of the results.
- **parametros** (object) - The parameters used for the query.

### Response Example
```json
{
    "municipios": [
        {
            "centroide_lat": -27.816619,
            "centroide_lon": -65.199594,
            "id": "908210",
            "nombre": "Taco Ralo",
            "provincia_id": "90",
            "provincia_nombre": "Tucumán"
        },
        { ... } // 9 municipios omitidos
    ],
    "cantidad": 10,
    "total": 112,
    "inicio": 0,
    "parametros": { ... }
}
```
```

--------------------------------

### Search Departments

Source: https://datosgobar.github.io/georef-ar-api/quick-start

This endpoint allows you to search for departments within a specific province, with an option to limit the number of results.

```APIDOC
## GET /departamentos

### Description
Searches for departments within a specified province, with an option to limit the quantity of results.

### Method
GET

### Endpoint
`https://apis.datos.gob.ar/georef/api/departamentos`

### Query Parameters
- **provincia** (string) - Required - The name of the province to search within.
- **max** (integer) - Optional - The maximum number of departments to return.

### Response
#### Success Response (200)
- **departamentos** (array) - A list of matching departments.
  - **id** (string) - The department ID.
  - **centroide** (object) - The centroid coordinates of the department.
    - **lat** (number) - Latitude.
    - **lon** (number) - Longitude.
  - **nombre** (string) - The name of the department.
  - **provincia** (object) - Information about the province the department belongs to.
    - **id** (string) - The province ID.
    - **nombre** (string) - The name of the province.
- **cantidad** (integer) - The number of departments returned.
- **total** (integer) - The total number of matching departments.
- **inicio** (integer) - The starting index of the results.
- **parametros** (object) - The parameters used for the query.

### Response Example
```json
{
    "departamentos": [
        {
            "id": "38042",
            "centroide": {
                "lat": -24.194923,
                "lon": -65.12645
            },
            "nombre": "PALPALÁ",
            "provincia": {
                "id": "38",
                "nombre": "JUJUY"
            }
        },
        { ... } // 15 departamentos omitidos
    ],
    "cantidad": 16,
    "total": 16,
    "inicio": 0,
    "parametros": { ... }
}
```
```

--------------------------------

### GET /ubicacion

Source: https://datosgobar.github.io/georef-ar-api/geom-operations

Determina la provincia, departamento y municipio (si existe) que contienen a un punto geográfico definido por coordenadas latitud y longitud.

```APIDOC
## GET /ubicacion

### Description
Enriquece datos existentes identificando la jerarquía administrativa de un punto geográfico.

### Method
GET

### Endpoint
/ubicacion

### Parameters
#### Query Parameters
- **lat** (float) - Required - Latitud del punto
- **lon** (float) - Required - Longitud del punto

### Request Example
GET https://apis.datos.gob.ar/georef/api/ubicacion?lat=-27.2741&lon=-66.7529

### Response
#### Success Response (200)
- **ubicacion** (object) - Objeto conteniendo provincia, departamento y municipio

#### Response Example
{
    "ubicacion": {
        "departamento": {"id": "10035", "nombre": "Belén"},
        "lat": -27.2741,
        "lon": -66.7529,
        "municipio": {"id": "100077", "nombre": "Hualfín"},
        "provincia": {"id": "10", "nombre": "Catamarca"}
    }
}
```

--------------------------------

### Consultar listas de referencia con pandas

Source: https://datosgobar.github.io/georef-ar-api/python-usage

Fetches reference lists from the API in CSV format and loads them into a pandas DataFrame. This allows for easy access to territorial unit lists. Dependencies include the pandas library.

```python
import pandas as pd

provincias = pd.read_csv("https://apis.datos.gob.ar/georef/api/provincias?formato=csv")

```

--------------------------------

### Configure Nginx cache for Georef API

Source: https://datosgobar.github.io/georef-ar-api/deploy

This snippet demonstrates how to configure Nginx to use a cache for the Georef API. It includes the Nginx configuration directive for setting up the cache path, levels, and validity. It also shows how to create the cache directory.

```nginx
proxy_cache_path /data/nginx/cache levels=1:2 inactive=120m keys_zone=georef:10m use_temp_path=off;

# Ensure the cache directory exists:
sudo mkdir -p /data/nginx/cache
```

--------------------------------

### POST /georef/api/{resource}

Source: https://datosgobar.github.io/georef-ar-api/bulk

Performs multiple queries to a specified API resource in a single request. Accepts the same parameters as the GET version, but all parameters must be sent in the request body, and the 'formato' parameter must be 'json'.

```APIDOC
## POST /georef/api/{resource}

### Description
This endpoint allows you to perform multiple queries to a specified API resource in a single HTTP request. It is designed to improve efficiency by reducing the number of round trips required for multiple data lookups.

### Method
POST

### Endpoint
`https://apis.datos.gob.ar/georef/api/{resource}`

Where `{resource}` is the API endpoint you want to query (e.g., `provincias`, `departamentos`, `localidades`).

### Parameters
#### Request Body
- **{resource}** (array) - Required - An array of objects, where each object represents a single query to the specified resource. Each query object should contain the parameters accepted by the `GET` version of the resource.
  - **formato** (string) - Required - Must be set to `"json"`.
  - Other parameters depend on the specific resource being queried (e.g., `nombre`, `campos`, `max`).

### Request Example
```json
{
    "provincias": [
        {
            "nombre": "cordoba",
            "campos": "nombre"
        },
        {
            "nombre": "chaco",
            "campos": "nombre"
        },
        {
            "nombre": "san luis",
            "campos": "nombre"
        }
    ]
}
```

### Response
#### Success Response (200)
- **resultados** (array) - Contains the results for each individual query submitted in the request. Each element in this array corresponds to one query and has the same structure as the response from the `GET` version of the resource.
  - **cantidad** (integer) - The number of results found for this specific query.
  - **inicio** (integer) - The starting index of the results for this query.
  - **{resource}** (array) - The actual results for the query (e.g., `provincias`, `departamentos`).
  - **total** (integer) - The total number of available results for this query.
  - **parametros** (object) - The parameters used for this specific query.

#### Response Example
```json
{
    "resultados": [
        {
            "cantidad": 1,
            "inicio": 0,
            "provincias": [
                {
                    "id": "14",
                    "nombre": "Córdoba"
                }
            ],
            "total": 1,
            "parametros": { ... }
        },
        {
            "cantidad": 1,
            "inicio": 0,
            "provincias": [
                {
                    "id": "22",
                    "nombre": "Chaco"
                }
            ],
            "total": 1,
            "parametros": { ... }
        },
        {
            "cantidad": 1,
            "inicio": 0,
            "provincias": [
                {
                    "id": "74",
                    "nombre": "San Luis"
                }
            ],
            "total": 1,
            "parametros": { ... }
        }
    ]
}
```

### Constraints
- The number of queries in a single request must not exceed 1000.
- The sum of all `max` parameters across all queries in a single request must not exceed 5000.
```

--------------------------------

### Ejemplo de respuesta JSON para consulta por lotes

Source: https://datosgobar.github.io/georef-ar-api/bulk

Esta es la estructura de respuesta JSON esperada al realizar una consulta por lotes. Contiene una lista 'resultados', donde cada elemento representa el resultado de una consulta individual, manteniendo la misma estructura que las respuestas GET.

```json
{
    "resultados": [
        {
            "cantidad": 1,
            "inicio": 0,
            "provincias": [
                {
                    "id": "14",
                    "nombre": "Córdoba"
                }
            ],
            "total": 1,
            "parametros": { ... }
        },
        {
            "cantidad": 1,
            "inicio": 0,
            "provincias": [
                {
                    "id": "22",
                    "nombre": "Chaco"
                }
            ],
            "total": 1,
            "parametros": { ... }
        },
        {
            "cantidad": 1,
            "inicio": 0,
            "provincias": [
                {
                    "id": "74",
                    "nombre": "San Luis"
                }
            ],
            "total": 1,
            "parametros": { ... }
        }
    ]
}
```

--------------------------------

### Containerized Deployment Workflow

Source: https://datosgobar.github.io/georef-ar-api/georef-api-development

Steps to clone the repository, configure the environment, launch Docker containers, and perform initial indexing.

```bash
git clone https://github.com/datosgobar/georef-ar-api.git
cd georef-ar-etl
cp docker/georef.example.cfg config/georef.cfg
cd docker
docker-compose up -d
docker-compose exec app make index
curl localhost:5000/api/provincias
```

--------------------------------

### Normalize geographic entity with Python requests

Source: https://datosgobar.github.io/georef-ar-api/python-usage

Demonstrates how to perform a GET request to normalize a single geographic entity name. It uses the urllib library to encode parameters and returns the parsed JSON response.

```python
import requests
import urllib

API_BASE_URL = "https://apis.datos.gob.ar/georef/api/"

def get_similar(endpoint, nombre, **kwargs):
    kwargs["nombre"] = nombre
    url = "{}{}?{}".format(API_BASE_URL, endpoint, urllib.urlencode(kwargs))
    return requests.get(url).json()[endpoint]

provincias = get_similar("provincias", "San Juan")
```

--------------------------------

### Instalar dependencias para compilar Python

Source: https://datosgobar.github.io/georef-ar-api/python3.6

Instala las dependencias necesarias en sistemas basados en Debian/Ubuntu para compilar Python desde el código fuente. Estas bibliotecas son requeridas por el proceso de construcción de Python.

```bash
$ sudo apt install make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev
```

--------------------------------

### Execute API Servers and Health Checks

Source: https://datosgobar.github.io/georef-ar-api/georef-api-development

Commands to launch development servers and verify API availability via HTTP requests.

```bash
make start_dev_server
make start_gunicorn_dev_server
curl localhost:5000/api/provincias
```

--------------------------------

### Clonar repositorio pyenv

Source: https://datosgobar.github.io/georef-ar-api/python3.6

Clona el repositorio oficial de pyenv en el directorio especificado (~/.pyenv). Este paso es necesario para obtener la herramienta de gestión de versiones de Python.

```bash
$ git clone https://github.com/pyenv/pyenv.git ~/.pyenv
```

--------------------------------

### Instalar Python 3.6.5 con pyenv

Source: https://datosgobar.github.io/georef-ar-api/python3.6

Utiliza pyenv para descargar, compilar e instalar la versión específica de Python 3.6.5. Este comando se encarga de todo el proceso de construcción y configuración de la versión de Python.

```bash
$ pyenv install 3.6.5
```

--------------------------------

### GET /localidades-censales

Source: https://datosgobar.github.io/georef-ar-api/localities

Retrieves a list of census localities as defined by INDEC for national censuses.

```APIDOC
## GET /localidades-censales

### Description
Returns a list of census localities, which are spatial concentrations of physical objects connected by street networks, defined by INDEC.

### Method
GET

### Endpoint
/localidades-censales

### Parameters
#### Query Parameters
- **nombre** (string) - Optional - Filter by locality name
- **max** (integer) - Optional - Maximum number of results

### Request Example
GET /localidades-censales?nombre=Buenos+Aires

### Response
#### Success Response (200)
- **localidades_censales** (array) - List of census locality objects

#### Response Example
{
  "localidades_censales": [
    {
      "id": "06000010001",
      "nombre": "Buenos Aires"
    }
  ]
}
```

--------------------------------

### Activar Python 3.6.5 y verificar instalación

Source: https://datosgobar.github.io/georef-ar-api/python3.6

Clona el repositorio del proyecto, navega a su directorio, activa la versión de Python 3.6.5 para ese directorio usando pyenv, y verifica que los comandos 'python' y 'pip' apunten a la versión correcta.

```bash
$ git clone https://github.com/datosgobar/georef-ar-api.git
$ cd georef-ar-api
$ pyenv version 3.6.5
$ python --version
Python 3.6.5
$ pip --version
pip 9.0.1 (python 3.6.5)
```

--------------------------------

### Configuración de entorno local en Ubuntu

Source: https://datosgobar.github.io/georef-ar-api/etl-install

Instalación de dependencias del sistema operativo, incluyendo PostgreSQL, PostGIS y herramientas GDAL necesarias para el procesamiento de datos.

```bash
sudo add-apt-repository -y ppa:ubuntugis/ppa
sudo apt update
sudo apt install postgresql-9.5 postgresql-9.5-postgis-2.4 gdal-bin libpq-dev
```

--------------------------------

### Run Tests and Code Quality Checks

Source: https://datosgobar.github.io/georef-ar-api/georef-api-development

Commands to execute unit tests and perform static code analysis to ensure style compliance and error-free code.

```bash
make test
make code_checks
```

--------------------------------

### Activar configuración de .bashrc

Source: https://datosgobar.github.io/georef-ar-api/python3.6

Recarga la configuración del shell para que los cambios realizados en el archivo ~/.bashrc surtan efecto inmediatamente. Esto permite que los comandos de pyenv sean reconocidos.

```bash
$ source ~/.bashrc
```

--------------------------------

### Gestión de entorno virtual Python

Source: https://datosgobar.github.io/georef-ar-api/etl-install

Instrucciones para crear un entorno virtual de Python e instalar las dependencias del proyecto utilizando pip o conda.

```bash
# Usando venv
python3 -m venv env
source env/bin/activate
pip install -r requirements.txt

# Usando Anaconda
conda install psycopg2
conda install gdal
pip install -r requirements.txt
```

--------------------------------

### Configuración de entorno Docker

Source: https://datosgobar.github.io/georef-ar-api/etl-install

Comandos para preparar el archivo de configuración y levantar los servicios necesarios mediante Docker Compose.

```bash
cp docker/georef.example.cfg config/georef.cfg
cd docker
docker-compose up -d
```

--------------------------------

### Configurar pyenv en .bashrc

Source: https://datosgobar.github.io/georef-ar-api/python3.6

Agrega las variables de entorno necesarias para que pyenv funcione correctamente al archivo ~/.bashrc. Esto incluye la definición de PYENV_ROOT y la adición de pyenv al PATH, además de la inicialización de pyenv para el shell.

```bash
$ echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
$ echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
$ echo -e 'if command -v pyenv 1>/dev/null 2>&1; then\n  eval "$(pyenv init -)"\nfi' >> ~/.bashrc
```

--------------------------------

### Normalize Addresses

Source: https://datosgobar.github.io/georef-ar-api/quick-start

This endpoint normalizes a given address, providing structured information about its components and location.

```APIDOC
## GET /direcciones

### Description
Normalizes a given address, returning structured information including street, number, department, province, and geographic coordinates.

### Method
GET

### Endpoint
`https://apis.datos.gob.ar/georef/api/direcciones`

### Query Parameters
- **departamento** (string) - Required - The name of the department where the address is located.
- **direccion** (string) - Required - The address string to normalize.

### Response
#### Success Response (200)
- **direcciones** (array) - A list of normalized address results.
  - **altura** (object) - Information about the street number.
    - **unidad** (any) - Unit of the street number (e.g., null).
    - **valor** (integer) - The street number.
  - **calle** (object) - Information about the street.
    - **categoria** (string) - Category of the street (e.g., "CALLE").
    - **id** (string) - The street ID.
    - **nombre** (string) - The name of the street.
  - **calle_cruce_1** (object) - Information about the first intersecting street.
  - **calle_cruce_2** (object) - Information about the second intersecting street.
  - **departamento** (object) - Information about the department.
    - **id** (string) - The department ID.
    - **nombre** (string) - The name of the department.
  - **localidad_censal** (object) - Information about the census locality.
    - **id** (string) - The census locality ID.
    - **nombre** (string) - The name of the census locality.
  - **nomenclatura** (string) - The full normalized address string.
  - **piso** (any) - Floor number (e.g., null).
  - **provincia** (object) - Information about the province.
    - **id** (string) - The province ID.
    - **nombre** (string) - The name of the province.
  - **ubicacion** (object) - Geographic coordinates.
    - **lat** (number) - Latitude.
    - **lon** (number) - Longitude.
- **cantidad** (integer) - The number of normalized addresses returned.
- **total** (integer) - The total number of matching addresses.
- **inicio** (integer) - The starting index of the results.
- **parametros** (object) - The parameters used for the query.

### Response Example
```json
{
    "direcciones": [
        {
            "altura": {
                "unidad": null,
                "valor": 2950
            },
            "calle": {
                "categoria": "CALLE",
                "id": "0653901002985",
                "nombre": "FLORIDA"
            },
            "calle_cruce_1": {
                "categoria": null,
                "id": null,
                "nombre": null
            },
            "calle_cruce_2": {
                "categoria": null,
                "id": null,
                "nombre": null
            },
            "departamento": {
                "id": "06539",
                "nombre": "Merlo"
            },
            "localidad_censal": {
                "id": "06539010",
                "nombre": "Merlo"
            },
            "nomenclatura": "FLORIDA 2950, Merlo, Buenos Aires",
            "piso": null,
            "provincia": {
                "id": "06",
                "nombre": "Buenos Aires"
            },
            "ubicacion": {
                "lat": -34.71409079053823,
                "lon": -58.73469942899891
            }
        }
    ],
    "cantidad": 1,
    "total": 1,
    "inicio": 0,
    "parametros": { ... }
}
```
```

--------------------------------

### List Streets

Source: https://datosgobar.github.io/georef-ar-api/quick-start

This endpoint lists streets within a specific department, allowing filtering by category.

```APIDOC
## GET /calles

### Description
Lists streets within a specified department, with an option to filter by street category.

### Method
GET

### Endpoint
`https://apis.datos.gob.ar/georef/api/calles`

### Query Parameters
- **departamento** (string) - Required - The name of the department to search within.
- **categoria** (string) - Optional - The category of streets to filter by (e.g., `avenida`).

### Response
#### Success Response (200)
- **calles** (array) - A list of matching streets.
  - **altura** (object) - Information about street numbering ranges.
    - **fin** (object) - End of the range.
      - **derecha** (integer) - Right side numbering.
      - **izquierda** (integer) - Left side numbering.
    - **inicio** (object) - Start of the range.
      - **derecha** (integer) - Right side numbering.
      - **izquierda** (integer) - Left side numbering.
  - **departamento** (object) - Information about the department.
    - **id** (string) - The department ID.
    - **nombre** (string) - The name of the department.
  - **localidad_censal** (object) - Information about the census locality.
    - **id** (string) - The census locality ID.
    - **nombre** (string) - The name of the census locality.
  - **id** (string) - The street ID.
  - **nombre** (string) - The name of the street.
  - **nomenclatura** (string) - The full street designation.
  - **provincia** (object) - Information about the province.
    - **id** (string) - The province ID.
    - **nombre** (string) - The name of the province.
  - **categoria** (string) - The category of the street (e.g., "AV").
- **cantidad** (integer) - The number of streets returned.
- **total** (integer) - The total number of matching streets.
- **inicio** (integer) - The starting index of the results.
- **parametros** (object) - The parameters used for the query.

### Response Example
```json
{
    "calles": [
        {
            "altura": {
                "fin": {
                    "derecha": 0,
                    "izquierda": 0
                },
                "inicio": {
                    "derecha": 0,
                    "izquierda": 0
                }
            },
            "departamento": {
                "id": "90077",
                "nombre": "Río Chico"
            },
            "localidad_censal": {
                "id": "90077010",
                "nombre": "Aguilares"
            },
            "id": "9007701000050",
            "nombre": "AV GRL SAVIO",
            "nomenclatura": "AV GRL SAVIO, Río Chico, Tucumán",
            "provincia": {
                "id": "90",
                "nombre": "Tucumán"
            },
            "categoria": "AV"
        },
        { ... } // 2 resultados omitidos
    ],
    "cantidad": 3,
    "total": 3,
    "inicio": 0,
    "parametros": { ... }
}
```
```

--------------------------------

### Clonación del repositorio Georef ETL

Source: https://datosgobar.github.io/georef-ar-api/etl-install

Comandos para descargar el código fuente del proyecto desde GitHub y acceder al directorio raíz.

```bash
git clone https://github.com/datosgobar/georef-ar-etl.git
cd georef-ar-etl
```

--------------------------------

### Search Localities

Source: https://datosgobar.github.io/georef-ar-api/quick-start

This endpoint allows you to search for localities within a specific province and retrieve specific fields.

```APIDOC
## GET /localidades

### Description
Searches for localities within a specified province and allows selection of specific fields to return.

### Method
GET

### Endpoint
`https://apis.datos.gob.ar/georef/api/localidades`

### Query Parameters
- **provincia** (string) - Required - The name of the province to search within.
- **campos** (string) - Optional - A comma-separated list of fields to include in the response (e.g., `nombre`, `id`).

### Response
#### Success Response (200)
- **localidades** (array) - A list of matching localities.
  - **id** (string) - The locality ID.
  - **nombre** (string) - The name of the locality.
- **cantidad** (integer) - The number of localities returned.
- **total** (integer) - The total number of matching localities.
- **inicio** (integer) - The starting index of the results.
- **parametros** (object) - The parameters used for the query.

### Response Example
```json
{
    "localidades": [
        {
            "id": "26007030000",
            "nombre": "PUERTO PIRAMIDE"
        },
        { ... } // 9 resultados omitidos
    ],
    "cantidad": 10,
    "total": 90,
    "inicio": 0,
    "parametros": { ... }
}
```
```

--------------------------------

### Configuración de base de datos PostgreSQL

Source: https://datosgobar.github.io/georef-ar-api/etl-install

Sentencias SQL para crear la base de datos, el usuario de servicio y habilitar la extensión PostGIS necesaria para datos geoespaciales.

```sql
create database georef_ar_etl with encoding = 'utf-8';
create user georef with login password 'changeme';
\c georef_ar_etl
create extension postgis;
grant all privileges on all tables in schema public to georef;
```

--------------------------------

### Download Geometries (Shapefile Format)

Source: https://datosgobar.github.io/georef-ar-api/shapefiles

This section details how to download geometries in ESRI Shapefile format. By appending `formato=shp` to the query parameters, the API will return a ZIP file containing the geometry data.

```APIDOC
## GET /georef/api/calles

### Description
Downloads street geometries in ESRI Shapefile format for a specified municipality.

### Method
GET

### Endpoint
https://apis.datos.gob.ar/georef/api/calles

### Query Parameters
- **interseccion** (string) - Required - Specifies the municipality ID (e.g., `municipio:141372`).
- **formato** (string) - Required - Set to `shp` for Shapefile format.
- **max** (integer) - Optional - Maximum number of results to return.

### Request Example
```
GET https://apis.datos.gob.ar/georef/api/calles?interseccion=municipio:141372&formato=shp&max=1000
```

### Response
#### Success Response (200)
- **file** (zip) - A ZIP file containing .shp, .shx, .dbf, and .prj files.

## GET /georef/api/departamentos

### Description
Downloads department geometries in ESRI Shapefile format for a specified province.

### Method
GET

### Endpoint
https://apis.datos.gob.ar/georef/api/departamentos

### Query Parameters
- **provincia** (string) - Required - The name of the province (e.g., `chaco`).
- **formato** (string) - Required - Set to `shp` for Shapefile format.
- **max** (integer) - Optional - Maximum number of results to return.

### Request Example
```
GET https://apis.datos.gob.ar/georef/api/departamentos?provincia=chaco&formato=shp&max=1000
```

### Response
#### Success Response (200)
- **file** (zip) - A ZIP file containing .shp, .shx, .dbf, and .prj files.
```

--------------------------------

### GET /direcciones

Source: https://datosgobar.github.io/georef-ar-api/addresses

Endpoint para normalizar y georreferenciar una dirección específica mediante parámetros de consulta.

```APIDOC
## GET /direcciones

### Description
Normaliza una dirección ingresada como texto y devuelve información detallada, incluyendo coordenadas geográficas (lat/lon) y datos administrativos normalizados.

### Method
GET

### Endpoint
https://apis.datos.gob.ar/georef/api/direcciones

### Parameters
#### Query Parameters
- **direccion** (string) - Required - Dirección a normalizar (ej: "Av. Santa Fe 260").
- **provincia** (string) - Optional - Nombre o ID de la provincia para filtrar resultados.
- **departamento** (string) - Optional - Nombre o ID del departamento para filtrar resultados.
- **localidad** (string) - Optional - Nombre o ID de la localidad para filtrar resultados.

### Request Example
GET https://apis.datos.gob.ar/georef/api/direcciones?direccion=Av. Santa Fe 260&provincia=cordoba

### Response
#### Success Response (200)
- **cantidad** (integer) - Cantidad de resultados devueltos.
- **direcciones** (array) - Lista de objetos con la información normalizada de las direcciones.
- **nomenclatura** (string) - Versión normalizada de la dirección.
- **ubicacion** (object) - Coordenadas latitud y longitud.

#### Response Example
{
    "cantidad": 1,
    "direcciones": [
        {
            "calle": {
                "nombre": "AV SANTA FE",
                "id": "1401401002460"
            },
            "nomenclatura": "AV SANTA FE 260, Capital, Córdoba",
            "ubicacion": {
                "lat": -31.408,
                "lon": -64.200
            }
        }
    ]
}
```

--------------------------------

### Ejecución de tareas ETL y migraciones

Source: https://datosgobar.github.io/georef-ar-api/etl-install

Comandos para ejecutar las migraciones de base de datos y el proceso ETL principal dentro del contenedor de la aplicación.

```bash
docker-compose exec app make migrate
docker-compose exec app make run
```

--------------------------------

### GET /departamentos - CABA Comunas

Source: https://datosgobar.github.io/georef-ar-api/communes

Retrieves a list of Comunas (districts) for the Autonomous City of Buenos Aires (CABA). The IDs and names are based on INDEC's Resolution 55/2019.

```APIDOC
## GET /departamentos - CABA Comunas

### Description
This endpoint provides access to the Comunas (districts) of the Autonomous City of Buenos Aires (CABA). The data adheres to the official IDs and names defined by INDEC's Resolution 55/2019.

### Method
GET

### Endpoint
/departamentos

### Parameters
#### Query Parameters
* **"deptos"** (string) - Optional - Filters the results to include only specific comuna IDs. Multiple IDs can be provided, separated by commas.

### Request Example
```json
{
  "example": "GET /departamentos?deptos=02007,02014"
}
```

### Response
#### Success Response (200)
- **"id"** (string) - The official ID of the Comuna.
- **"nombre"** (string) - The official name of the Comuna.

#### Response Example
```json
{
  "example": [
    {
      "id": "02007",
      "nombre": "Comuna 1"
    },
    {
      "id": "02014",
      "nombre": "Comuna 2"
    }
  ]
}
```
```

--------------------------------

### Ejemplo de consulta por lotes con cURL

Source: https://datosgobar.github.io/georef-ar-api/bulk

Este ejemplo demuestra cómo realizar una consulta por lotes utilizando el comando cURL. Se envían múltiples peticiones para obtener información de provincias, especificando los campos deseados en el cuerpo de la solicitud POST.

```bash
curl -X POST https://apis.datos.gob.ar/georef/api/provincias \
-H "Content-Type: application/json" \
-d '{
    "provincias": [
        {
            "nombre": "cordoba",
            "campos": "nombre"
        },
        {
            "nombre": "chaco",
            "campos": "nombre"
        },
        {
            "nombre": "san luis",
            "campos": "nombre"
        }
    ]
}'
```

--------------------------------

### Search Localities via Georef API

Source: https://datosgobar.github.io/georef-ar-api/quick-start

Fetches a list of localities filtered by province, with the response limited to specific fields using the 'campos' parameter.

```http
GET https://apis.datos.gob.ar/georef/api/localidades?provincia=chubut&campos=nombre
```

```json
{
    "localidades": [
        {
            "id": "26007030000",
            "nombre": "PUERTO PIRAMIDE"
        }
    ],
    "cantidad": 10,
    "total": 90,
    "inicio": 0,
    "parametros": { ... }
}
```

--------------------------------

### Execute ETL Process via CLI

Source: https://datosgobar.github.io/georef-ar-api/etl-install

Commands to trigger the ETL pipeline. Users can run the full suite via Make or target specific geographic entities using the Python module directly.

```bash
(env) $ make run
```

```bash
(env) $ python -m georef_ar_etl -p provincias -p departamentos
```