# MATLAB Geocoding Tutorial

## OpenCage Geocoding API MATLAB Tutorial

Tutorial for using the OpenCage Geocoding API in MATLAB - An API for reverse and forward geocoding using open geo data

This is a tutorial for using the [OpenCage geocoding API](https://opencagedata.com/api) in MATLAB.

Alexander Dentler has created two MATLAB functions, one for forward geocoding `OpenCageForward `, and one for reverse ` OpenCageReverse`.

Please find the code for each [in the opencage-matlab repository on GitHub](https://github.com/OpenCageData/opencage-matlab).

### Background

The code examples below will use your geocoding API key once you [log in](https://opencagedata.com/users/sign_in).

#### Before we dive in to the tutorial

1. [Sign up](https://opencagedata.com/users/sign_up) for an OpenCage geocoding API key.
2. Play with the [demo page](https://opencagedata.com/demo), so that you see the actual response the API returns.
3. Browse the [API reference](https://opencagedata.com/api), so you understand the [optional parameters](https://opencagedata.com/api#optional-params), [best practices](https://opencagedata.com/api#bestpractices), [possible response codes](https://opencagedata.com/api#codes), and the [rate limiting](https://opencagedata.com/api#rate-limiting) on free trial accounts.

Working with AI?

We offer an [Agent Skill](https://github.com/OpenCageData/opencage-skills) to make it easy for AI to quickly learn about our geocoding API.

### Example

    %% INIT
    clear
    clc
    close all
    
    %% Parameters
    key='YOUR-API-KEY';
    
    %% Forward search
    q='Prinsengracht 263-267, 1016 GV Amsterdam, Netherlands';
    % plain search with one result
    [results]=OpenCageForward(key,q);
    % first result gives us longitude and latitude of the road we are
    % looking for, second result is just Amsterdam
    disp(results.results(1).formatted)
    disp('is a')
    disp(results.results(1).components.x_type)
    disp(results.results(2).formatted)
    disp('is a')
    disp(results.results(2).components.x_type)
    % Let us say we are interested in the geo info of London, and let us
    % allow for up to the maximum number of results: 100
    q='London';
    [results]=OpenCageForward(key,q,'limit','100');
    % we get 50 results. Say we want to restrict our search to the UK. We set
    [results]=OpenCageForward(key,q,'limit','100','countrycode','uk');
    % we get 3 results
    disp(results.results(1).formatted)
    disp('is a')
    disp(results.results(1).components.x_type)
    disp(results.results(2).formatted)
    disp('is a')
    disp(results.results(2).components.x_type)
    disp(results.results(3).formatted)
    disp('is a')
    disp(results.results(3).components.x_type)
    
    
    %% Reverse search
    q='0 0';
    [results]=OpenCageReverse(key,'0 0');

### Further Reading

- [OpenCage geocoding API Reference](https://opencagedata.com/api)
- [Comparing geocoding services](https://opencagedata.com/guides/how-to-compare-and-test-geocoding-services)
- [Cleaning / formatting your forward geocoding query](https://opencagedata.com/guides/how-to-format-your-geocoding-query)
- [Geocoding more quickly](https://opencagedata.com/guides/how-to-geocode-more-quickly)
- [Geocoding large datasets](https://opencagedata.com/guides/how-to-geocode-large-datasets)
- [Geocoding and preserving privacy](https://opencagedata.com/guides/how-to-preserve-privacy-by-showing-only-an-imprecise-location)
- [Sample address and coordinate lists for testing](https://opencagedata.com/tools/address-lists)